Skip to content

Project Specifications

Rules that bind this codebase only. They cover deployment choices, such as running the CASE_MANAGER as an actor separate from the Case Owner, performance and operating limits, how a receiver records what it receives, and core internals. Naming a Python path, library, or class does not by itself make a rule a project rule: who must obey the rule decides its kind.

Behavioral Specifications

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

Activity Factory Functions

Requirements governing the factory function API for constructing outbound Vultron protocol activities. Factory functions are the sole public construction API for activity objects outside the wire vocabulary layer, replacing direct subclass instantiation to enforce consistent field population and layer separation.

File ID: AF

Purpose and Scope

ID Priority Requirement Related
AF-01-001 MUST Factory functions MUST be the sole public construction API for outbound Vultron protocol activities

When every outbound activity is built in one place, the rules for its fields are applied in one place. Code that instantiates an activity class directly can skip a field or a check that the factory applies. The recipient then gets an incomplete activity.
AF-01-002 MUST Factory functions MUST return plain AS2 base types (e.g. as_Offer, as_Accept, as_Create) rather than Vultron activity subclasses

Callers depend only on the standard AS2 types. The internal activity subclasses can then change without a change to any caller. Callers also cannot come to depend on behavior that only an internal subclass has.
AF-01-003 MUST Factory function signatures MUST declare explicit, domain-typed parameters for all protocol-significant fields

Explicit, typed parameters let the type checkers and the reader see what each factory needs. A generic dict or Any parameter hides a missing or wrong protocol field until run time, or until a recipient refuses the activity.
AF-01-004 SHOULD Factory functions SHOULD accept **kwargs for optional AS2 fields that are not protocol-significant, forwarding them to the underlying AS2 constructor

Fields such as summary and in_reply_to apply to many activities and do not change what the activity means. The time is not one of them: published is the required at, set in one place (ADR-0176). When the factory passes them through **kwargs, each signature stays short, and no factory needs one parameter for each optional AS2 field.
AF-01-005 MUST When the fields of a domain entity decide how a factory enriches the wire object, the factory MUST accept the complete domain object. An example is a case whose embargo state decides whether activeEmbargo appears in the stub.

The core class is its own wire form (ARCH-25-003, ADR-0211), and ARCH-22-001 lets the wire layer import it. The factory thus needs no separate wire copy of the object, and it can read every field the object has.
AF-01-006 MUST A factory that accepts a domain entity (AF-01-005) MUST derive the enrichment from that object's own fields.

When two places compute the same enrichment, the results drift apart. When the factory derives it from the object's own fields, the wire object always agrees with the domain object.
Extends: AF-01-005
AF-01-007 MUST NOT A caller MUST NOT hand a factory a hand-built partial stub in place of the domain object, such as a CasePreview assembled field by field.

A partial stub that a caller builds field by field can omit a field the object supplies, for example end_time on an embargo event. The recipient then gets less than the sender knows.
AF-01-008 MUST NOT A factory MUST NOT spell an AS2 field name by hand. The field alias a core object inherits (ARCH-12-013) is the only source of the wire spelling, and delivery renders through the port (ARCH-20-001).

When the inherited alias is the only source of each wire spelling, a factory cannot spell a field differently from the rest of the system.
Uses definition from: ARCH-12-013
See also: ARCH-20-001 — context for the reader

Module Structure

ID Priority Requirement Related
AF-02-001 MUST All factory functions MUST live in the vultron/wire/as2/factories/ package — a sibling of vultron/wire/as2/vocab/

One package for every factory gives callers one import location. It also gives the import-boundary test (AF-06-001) one directory to allow. A factory outside that package would be a way to build activities that the test does not check.
AF-02-002 MUST The factories/ package MUST hold one module per protocol domain, one for each module in vocab/activities/, such as embargo.py, report_management.py and case_management.py.

A factory module for each vocabulary module lets a reader find the factory for an activity from the module of its class.
AF-02-005 MUST A change that adds a vocab/activities/ module MUST add its factories/ module in the same change.

A new vocabulary module with no factory module has activities that only direct instantiation can build, which AF-01-001 forbids.
Extends: AF-02-002
AF-02-003 MUST factories/__init__.py MUST re-export every factory function from all domain modules so callers can use a single from vultron.wire.as2.factories import ... import

One import path keeps call sites short. The package can also move a factory between its domain modules without a change to any caller.

Function Naming

ID Priority Requirement Related
AF-03-001 MUST Factory function names MUST be the snake_case equivalent of the corresponding Vultron activity class name

A predictable name lets a reader find the factory from the activity class, and the class from the factory. It also prevents two different names for the same activity.

Error Handling

ID Priority Requirement Related
AF-04-001 MUST Every factory function MUST wrap Pydantic ValidationError in VultronActivityConstructionError

A caller must not need to know that the factories use Pydantic. One domain exception for every construction failure gives callers one type to catch. The Pydantic error stays attached as its cause, for diagnosis.
AF-04-002 MUST vultron/wire/as2/factories/__init__.py MUST re-export VultronActivityConstructionError, which vultron/errors.py defines.

Callers import the factories from vultron.wire.as2.factories. When the package also exports the exception, a caller can catch construction failures without an import from a second module. The class is defined in vultron/errors.py with the rest of the shared hierarchy, under VultronError (EH-01-002).
AF-04-003 SHOULD Factory functions SHOULD log a WARNING before raising VultronActivityConstructionError so that construction failures are observable without requiring callers to catch the exception

A caller can catch the exception and handle it, and the failure is then hidden. A WARNING at the point of failure records which factory failed and why, even when a caller hides the exception.

Internal Vocabulary Classes

ID Priority Requirement Related
AF-05-001 MUST Vultron activity subclasses in vultron/wire/as2/vocab/activities/ MUST NOT be imported by any module outside that package or vultron/wire/as2/factories/

The internal subclasses are implementation details of the factories. When outside code cannot import them, it cannot build activities without a factory (AF-01-001). The subclasses can also change without a change to any caller.
AF-05-002 MUST Inside each factory function the corresponding internal class MUST be instantiated first; the result is returned typed as the plain AS2 base type

The internal subclass holds the validation and the fixed fields of its activity, such as its type and the shape of its object. The factory instantiates the subclass first, so those rules apply. The factory then returns the plain AS2 type, which keeps callers on the public types (AF-01-002).
AF-05-003 SHOULD Internal Vultron activity classes SHOULD be prefixed with _ or otherwise marked as private once factory functions exist for them, to signal that they are implementation details

A leading underscore tells readers and linters that a name is private. On an internal activity class, it shows that callers must use the factory and not the class.

Import Boundary Enforcement

ID Priority Requirement Related
AF-06-001 MUST A pytest test in test/architecture/ MUST verify that no Python source file outside vultron/wire/as2/vocab/activities/ and vultron/wire/as2/factories/ contains an import from vultron.wire.as2.vocab.activities

A rule about imports that no test checks erodes as soon as one module breaks it. An architecture test fails the build on the first import of an internal activity class from outside the allowed packages, so the factory boundary (AF-05-001) stays in place.
AF-06-002 MUST The test/architecture/ package MUST be a proper pytest package (__init__.py present) so that future architectural enforcement tests can be added alongside it

pytest needs __init__.py to treat the directory as a package, so that test modules with the same file name in other directories do not collide. Architecture tests can then share helpers in the package and grow next to each other.

TypeAlias Naming

ID Priority Requirement Related
AF-07-003 SHOULD A TypeAlias that a vocab/activities/ module defines for its own use only SHOULD carry a leading underscore.

A name used only in one module is private. A leading underscore keeps other modules from importing it and shows that it is not part of the public vocabulary.

Activity Translator Port

ID Priority Requirement Related
AF-09-001 MUST NOT A core use case in vultron/core/use_cases/ MUST NOT import from vultron/wire/ directly.

from_core() is a wire-layer method. Calling it directly from core use-cases inverts the hexagonal architecture dependency direction: core→wire. The Activity Translator port pattern maintains the correct direction (core defines the port; wire implements it) while providing the same functional capability.
Refines: ARCH-01-001
AF-09-003 MUST A core use case MUST turn domain objects into wire activities through the Activity Translator port. The port is a driven-adapter Protocol defined in vultron/core/, and an adapter in the wire layer implements it. It replaces the from_core() calls in vultron/core/use_cases/.

The use case still needs wire activities after AF-09-001 removes its wire imports. The port gives it that capability, and core keeps the dependency direction: core defines the port and the wire layer implements it.
Implements: AF-09-001
AF-09-002 MUST A use case MUST receive the Activity Translator port by dependency injection and not create the wire-layer translator itself. The port arrives as a constructor parameter or factory argument.

A use case that creates the translator itself must import the wire layer, which AF-09-001 forbids. Injection keeps that import out of core. It also lets a test give the use case a stub translator.
Extends: AF-09-003

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

DataLayer Isolation

ID Priority Requirement Related
AKM-01-001 MUST NOT Each Actor's DataLayer is private to that Actor and MUST NOT be accessible to any other Actor.

If one actor could read another's DataLayer, it would act on case data it was never sent, so its knowledge would not be bounded by the activities it received (AKM-02-001), and co-located actors would behave differently from the same actors on separate servers. A private store also keeps one actor's embargoed case data from reaching another actor that shares the deployment.

Knowledge Boundaries

ID Priority Requirement Related
AKM-02-004 MUST This codebase MUST carry inline every object that a recipient cannot be expected to hold already.

How this codebase meets AKM-02-002; split from it so AKM-02-002 states only what other participants observe (MS-12-010). This codebase dereferences only the few references AKM-05-007 lists, so a reference to an object its recipient does not hold could not in general be resolved. Carrying the object inline instead is a shortcut of this prototype reference implementation, not a protocol rule.
Implements: AKM-02-002
AKM-02-007 MUST This codebase MUST use a bare reference only for an object that its recipient already holds, such as the case it participates in.

How this codebase meets AKM-02-002, beside AKM-02-004. A bare reference to an object the recipient holds can be matched to that object, so the recipient can read what the activity acts on without a fetch.
Implements: AKM-02-002
AKM-02-005 MUST This codebase's activity factories MUST reduce a full case given as target to its URI and leave a case stub or a URI unchanged. Apart from the typed case reference AKM-03-004 requires in object, target is the one slot in which this codebase carries a case by reference rather than inline.

How this codebase meets AKM-02-003; split from it so AKM-02-003 states only the forms other participants observe in target (MS-12-010). That every other slot carries the case inline follows from this codebase's inline-object shortcut (AKM-02-004, AKM-03-003), not from the protocol; the acts AKM-03-004 names go only to actors that hold the case.
Implements: AKM-02-003
See also: AKM-03-004 — context for the reader

Outbound Activity Object Integrity

ID Priority Requirement Related
AKM-03-003 MUST Except for the case reference AKM-03-004 requires and the stub Invite's case reference carrying the case's preview (CM-11-013), this codebase MUST carry the object of every outbound activity as a fully inline typed object, never as a bare URI reference or an as_Link. AKM-03-002 enforces this at delivery.

How this codebase meets AKM-03-001 and MV-09-001; split from them so they state only what other participants observe (MS-12-010). A receiver of this codebase does not dereference (AKM-05-003), so it could not resolve a reference to learn the activity's semantic type. Carrying the object inline is a shortcut of this prototype reference implementation, not a protocol rule. A typed reference names its type, so a receiver still routes by it (ADR-0165).
Implements: AKM-03-001
Implements: MV-09-001
See also: CM-11-013 — the stub Invite's previewed case reference, the rule's other exception
AKM-03-004 MUST This codebase MUST carry the case that Join, Ignore and Leave of a case and the ownership-transfer Offer(VulnerabilityCase) act on as a typed reference: an inline object with only the case's id and type. The ownership-transfer Offer is both the one nested in the owner's proposal and the one the CASE_MANAGER makes.

Every receiver of these acts holds the case: the CASE_MANAGER holds the canonical case, and the transferee of an ownership-transfer Offer is an active participant (CM-21-021). A full copy would put the sender's view of the case on the ledger, where a replica could take records from it. The reference's type keeps routing by object type, as an actor reference does (ADR-0159).
Supersedes: AKM-03-003
AKM-03-005 MUST The CASE_MANAGER, receiving one of the acts AKM-03-004 names, MUST read only the case's id from the act's object and store nothing from it, taking every other detail from the case it holds, whether the object is a typed reference or a full case.

Another sender may still carry a full case in one of these acts. Refusing it would refuse a message the CASE_MANAGER understands, and storing any of it would let the sender's copy disagree with the canonical case. The body is still ledgered as received (CLP-07-011), so a replica reflecting the entry copies no record out of such an act's case either (ADR-0165).
Uses definition from: AKM-03-004
AKM-03-006 MUST The CASE_MANAGER MUST refuse one of the acts AKM-03-004 names that names a case it does not hold, naming the activity and the case in the reason.

The act carries no case to act on, so a receiver that does not hold the case has nothing to apply it to; naming both lets the sender see which act failed and why.
Uses definition from: AKM-03-004
AKM-03-002 MUST The outbox handler MUST enforce object integrity at delivery time as a last-resort runtime guard.

The activity factories enforce inline objects at construction (AKM-03-003), but an activity built on another path could still reach the outbox with a bare URI. Checking at delivery keeps such an activity from reaching a receiver that cannot resolve it, and reports the defect at the sender instead of as a misrouted activity at the receiver.
Verifies: AKM-03-003

Future: Known-Object Tracking

ID Priority Requirement Related
AKM-04-001 MAY A future implementation MAY track which objects have been shared with each participant (e.g., via CaseLedgerEntry hash-chain records) to avoid redundant full-object transmission.

Carrying every object inline on every activity repeats data the recipient already holds, and messages grow with the case. Knowing what each participant has been sent would let a sender use a reference for those objects safely (AKM-02-002). Nothing depends on it, so it is a MAY.

Actor Addressing and Resolution

ID Priority Requirement Related
AKM-05-006 MUST This codebase's CASE_MANAGER MUST serve a case object, at GET {actor}/cases/{case}/objects with an object_id query parameter, to an active participant of the case (CM-10-004) that has not closed on it (CM-23-004). A case object is the case itself, an embargo in its register, a participant, status, report, vulnerability item, case reference or note it lists, or an object whose context is the case. The {case} segment is the case's id, or its surrogate key when the id carries slashes. The surrogate key is the last segment of the id, and one that matches more than one case names none. The requester is the actor the request names in its X-Vultron-Actor header.

A replica dereferences a case object from the actor that holds the canonical case (ADR-0107), and only an active participant is entitled to case content (CM-10-004). A participant's replica is not the case host, so only the CASE_MANAGER serves the read.
Implements: AKM-05-003
Uses definition from: CM-10-004
Uses definition from: CM-23-004
AKM-05-009 MUST This codebase's CASE_MANAGER MUST answer 403, 401 or 404 when it refuses the AKM-05-006 read. It answers 403 to a requester that is not an entitled participant, and 401 to a request naming no requester. It answers 404 for a case it does not manage, or an object the case does not name.

A 404 for an object the case does not name, whether or not the host holds it, tells a participant nothing about cases it is not in. Distinct answers for a missing and a refused requester let the fetcher end at once on either (AKM-05-013).
Extends: AKM-05-006
AKM-05-008 MUST This codebase MUST make at most max_object_fetch_attempts attempts to fetch one object (default 3), backing off exponentially between them, each bounded by object_fetch_timeout_seconds (default 30).

A fetch that never succeeds must surface rather than hang (ADR-0107).
Implements: AKM-05-007
AKM-05-013 MUST This codebase MUST end a fetch at once on a 4xx answer.

A 4xx answer will not change on a retry (OX-13-005).
Refines: AKM-05-008
AKM-05-014 MUST This codebase MUST log at WARNING a fetch that fails, or answers with anything but the object asked for, naming the object, its holder and the waiting activities.

A failed fetch is recoverable for the inbox but leaves a replica without an object it was expected to hold, so an operator needs to see it (SL-01).
Extends: AKM-05-008
AKM-05-015 MUST After a fetch fails, this codebase MUST process each activity waiting on it without the object. The path that needs the object then refuses it as it did before dereference existed.

Replaying the waiting activity, instead of dead-lettering it, lets the handler that needs the object give the refusal and the answer it already gives for an object nobody can supply.
Extends: AKM-05-008

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

API Discoverability

ID Priority Requirement Related
AR-01-001 MUST The API MUST serve a machine-readable OpenAPI JSON schema in reply to GET /api/v2/openapi/v2.json.

An agent or a client generator reads the OpenAPI schema to learn the endpoints, their parameters and their response types. Without a machine-readable schema, each client must be written by hand from prose, and it goes out of date when the server changes. FastAPI builds the schema from the route declarations, so the schema follows the code.
AR-01-002 MUST The API MUST expose rendered documentation UI at /docs and /redoc in development environments

A rendered page lets a developer read the endpoints and try a request in a browser, with no client to write. Limiting the requirement to development environments lets a production deployment turn the pages off.
AR-01-003 MUST Every endpoint MUST have a unique, stable operationId following the {resource}_{action} naming convention

A client generator names each client method after the operationId, and an agent's tool definitions can use it too. A unique id prevents two methods with the same name. A stable id keeps generated clients and tool definitions working when the server code changes. FastAPI otherwise derives the id from the handler function name, the path and the method, so renaming a function or moving a route changes the id. A fixed naming pattern lets a reader find the id from the resource and the action.
AR-01-004 MUST All possible HTTP response codes for each endpoint MUST be declared in the OpenAPI spec with typed response models

An agent chooses its next step from the response code. If the schema leaves out a code, the agent cannot expect that code or parse its body. A typed response model for each code lets a client check every answer it can get.

State and Workflow Transitions

ID Priority Requirement Related
AR-02-001 SHOULD Resources with a status field SHOULD include a next_allowed_actions list identifying valid state transitions from the current state

Without a list of next actions, an agent must know the state machine to choose a valid request, and it learns of a wrong choice only from an error. A next_allowed_actions list tells the agent which requests the server accepts in the current state.
AR-02-002 MUST All valid states and state transitions for state machine resources MUST be documented

Clients, agents and reviewers need the full set of states and transitions to predict what a request does and to check the implementation against it. A transition that is not documented can be found only by reading the code or by trial and error.
AR-02-003 MUST Endpoints with prerequisites MUST return a structured error using the error field value "PreconditionFailedError" when invoked out of sequence

An agent that calls an endpoint too early must know that the order was wrong, not that its request was bad. A fixed error value, "PreconditionFailedError", lets the agent find this case and do the missing step first (EH-05-001).
Uses definition from: EH-05-001

Stable Error Types

ID Priority Requirement Related
AR-03-001 MUST The API MUST use the error field (per EH-05-001) as a stable, machine-parseable error type identifier

Agents choose what to do from the type of an error. The human-readable message can change its words between versions, so a program cannot depend on it. The error value, a code from the VultronError hierarchy (EH-05-001), stays the same when the message changes.
Extends: EH-05-001

Actor Discovery Profile

ID Priority Requirement Related
AR-10-001 MUST The API MUST expose GET /actors/{actor_id}/profile returning an ActivityStreams actor profile document for actor discovery and federation

The route path is this server's REST choice. A peer finds an actor from its id and the endpoints its actor document names (IE-02-001), never from a path convention, so another implementation may serve the document anywhere. Only this codebase must obey the path, so it is project (ADR-0134).
AR-10-003 MUST The profile endpoint MUST support both full actor URI and short actor ID (e.g., vendorco) as the actor_id path parameter

Accepting a short ID in the path is a convenience of this server's REST routes (AR-10-001); on the wire an actor is named by its full id (MV-05-001). Only this codebase must obey it, so it is project (ADR-0134).

CVD Action Rules API

ID Priority Requirement Related
AR-07-001 SHOULD The system SHOULD expose an endpoint that returns the set of valid CVD actions available to a participant given current case state and their role

The CVD actions that a participant can take depend on the case state and on the participant's role, across several state machines, so a client finds them hard to calculate correctly. Without an endpoint, each client must copy these rules and keep its copy current. An answer from the server gives every client the same answer and keeps the rules in one place.
AR-07-002 MUST The action rules response MUST be a machine-parseable JSON object that includes: (a) the current case state, (b) the requesting participant's CVD role, (c) a list of valid action identifiers available in the current state, and (d) for each unavailable action, the reason it is disallowed.

An agent needs the case state and the role to understand the answer. It needs the valid action identifiers to choose an action, and a reason for each action that is not available to explain the answer or to plan the next step. A JSON object lets a program read each of these parts.
AR-07-003 MUST The action rules endpoint MUST be reflected in the OpenAPI schema per AR-01-001

Clients find endpoints and their response formats in the OpenAPI schema (AR-01-001). An endpoint that is missing from the schema is not visible to generated clients or to agents that read the schema.
Uses definition from: AR-01-001
Uses definition from: AR-07-001

CLI Interface

ID Priority Requirement Related
AR-08-001 MUST The CLI MUST be installable as a Python package entry point defined in pyproject.toml

An entry point in pyproject.toml installs the CLI as a command when the package is installed. Agents and scripts can then run it by name, with no path to a script and no python -m.
AR-08-002 MUST Every CLI command MUST support a structured JSON output mode (e.g., --output json) emitting machine-parseable JSON to stdout

An agent reads command output with a program. Output for people changes its format and is hard to parse safely. A JSON mode gives the agent a fixed format on stdout.
AR-08-003 MUST CLI commands MUST exit with code 0 on success, 1 on handled error, and 2 on usage or argument error

A script or an agent chooses its next step from the exit code. Fixed codes let it tell success, a handled error and a wrong call apart without reading the output. Code 2 for a usage error is also the code that argparse and Click use.
AR-08-004 MUST CLI commands wrapping API calls MUST surface the error field and request_id from API error responses in their JSON error output

The error field tells an agent what failed, and the request_id lets a person find the request in the server logs. A CLI that drops these fields leaves the agent only a message to guess from.
AR-08-005 SHOULD Long-running CLI commands SHOULD support --wait / --no-wait flags; --no-wait returns the job object immediately

An agent may want to wait until a long operation ends, or it may want to start the operation and do other work. --wait and --no-wait let the caller choose. --no-wait returns the job object (AR-04-001), so the caller can check the operation later.

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-001 MUST NOT The core/ package (or equivalent domain layer) MUST NOT import from wire/, adapters/, or any external framework

Keeps domain logic replaceable without touching the wire or transport layer
ARCH-01-004 MUST This codebase MUST fix each ARCH-01-001 violation in vultron/core/ by moving its import behind a driven port.

Leaving core→wire import violations unfixed undermines the hexagonal boundary and prevents clean unit testing of core logic with mock adapters. See tracking issues for the current set of known violations.
Implements: ARCH-01-001 — ARCH-01-001 is the general constraint; ARCH-01-004 requires that all violations be systematically remediated via driven ports.
ARCH-01-007 MUST This codebase MUST give each core file that imports wire a narrow driven port in the SyncActivityPort or TriggerActivityPort pattern, or a wider shared port.

A narrow port names only the calls that one file needs, so a test can replace it with a small mock adapter. A shared port serves several files that need the same calls, so the code does not grow many ports that are almost the same.
Implements: ARCH-01-004
ARCH-01-005 MUST NOT Production adapters (HTTP routes, CLI commands, MCP server, background workers) MUST NOT import from vultron/demo/.

The demo layer contains simplified, non-production implementations of actors and data handling. Importing it in production adapters silently pulls in demo behaviour and dummy data, and couples production code to a layer with no stability guarantees.
ARCH-01-008 MUST This codebase MUST treat demo-layer modules as test-only code at runtime, outside the production dependency graph.

Demo modules hold simplified actors and dummy data, and they have no stability promise. If a production process loads them by any route, it runs that code in production.
Extends: ARCH-01-005
ARCH-01-006 MUST NOT Demo-layer modules (vultron/demo/**) MUST NOT import from the legacy simulator package (vultron/bt/**). The one exception is the unified demo CLI aggregator, vultron/demo/cli/vultrabot_commands.py (DC-01-001).

vultron/demo/ demonstrates the production protocol, and vultron/bt/ is the frozen legacy simulator that is to be retired (see notes/codebase-structure.md "Module Boundary"). cli.py is exempt as a thin aggregator: it is the one documented bridge to the bt-tree demos (pacman, robot, cvd), which it shows as a sub-group. Derives from ADR-0009 (hexagonal).
See also: DC-01-001 — context for the reader
ARCH-01-009 MUST The demo logic modules (vultron/demo/scenario/, vultron/demo/exchange/, vultron/demo/helpers/ and vultron/demo/fuzzer/) MUST stay free of any vultron/bt/ import.

The CLI aggregator is the one bridge to the legacy demos. If a logic module imports the legacy simulator, demo logic depends on code that is to be retired. That undoes the decoupling that vultron/demo/fuzzer/ exists to give.
Refines: ARCH-01-006

SemanticIntent Enum

ID Priority Requirement Related
ARCH-02-001 MUST The MessageSemantics enum (SemanticIntent) MUST be defined in the domain layer, not in the wire layer

Core code dispatches on MessageSemantics. If the enum is defined in the wire layer, core must import wire to dispatch, and ARCH-01-001 forbids that import. The semantic extractor in the wire layer can still produce the enum values, because the wire layer may import core models (ARCH-22-001).

Semantic Extractor

ID Priority Requirement Related
ARCH-03-001 MUST AS2 vocabulary MUST be mapped to domain concepts in exactly one location: the semantic extractor

When one module maps AS2 vocabulary to domain concepts, a change in the wire format changes only that module. If a second module also does the mapping, the two can disagree, and one message can mean different things in different parts of the code. The semantic extractor reads the AS2 form, so it is in vultron/wire/, which may import core models (ARCH-22-001, ADR-0211).

Driven Adapter Injection

ID Priority Requirement Related
ARCH-04-002 MUST SyncActivityPort MUST be defined as a typing.Protocol in vultron/core/ports/sync_activity.py with fire-and-forget methods, one per sync activity it builds: send_reject_log_entry(entry, tail_hash, actor_id, to, *, in_reply_to), send_read_ledger(case_id, ledger_position, actor_id, to), send_empty_chain_read(case_id, copy_tail_hash, actor_id, to, *, in_reply_to) and send_add_log_entry(entry, actor_id, to). send_add_log_entry reports whether a row was queued (bool; False when an identical row was already pending, SYNC-15-012); callers need not use the result, and no other value crosses the port back into core.

Sync use cases must send ledger activities, but core must not import wire types (ARCH-01-001). This port lets core give domain objects to an adapter, which builds and queues each wire activity. Core gets nothing back from the port except one bool from send_add_log_entry. That value lets a replay count only the rows that it really queued (SYNC-15-011), with no core read of the outbox (DL-06-001). See ADR-0112.
Implements: ARCH-04-001 — SyncActivityPort is the specific driven port for sync outbound activities
Implements: ARCH-01-001 — Eliminates wire imports from core sync use cases
Uses definition from: SYNC-15-012
ARCH-04-003 MUST The concrete adapter (SyncActivityAdapter) MUST be implemented in vultron/adapters/driven/sync_activity_adapter.py and own the full domain → wire → persist → outbox pipeline.

Concentrating the full domain → wire → persist → outbox pipeline in the adapter keeps wire concerns out of core and satisfies the baton-pass pattern.
ARCH-04-004 MUST Core use cases and BT nodes MUST call only the SyncActivityPort methods.

Calling only port methods enforces the hexagonal boundary and enables testing core logic with mock adapters.
Depends on: ARCH-04-002
ARCH-04-005 MUST NOT Core use cases and BT nodes MUST NOT import wire types (CaseLedgerEntry, WireCaseLedgerEntry) or wire factory functions (add_log_entry_activity, reject_log_entry_activity).

Wire type imports in core violate the hexagonal boundary; all wire concerns are handled exclusively by the SyncActivityAdapter.
Refines: ARCH-01-001

Connector Plugins

ID Priority Requirement Related
ARCH-05-001 MUST NOT Core MUST NOT import a connector plugin (tracker integration) directly.

A connector integrates one external tracker. If core imports a connector, core depends on that tracker's code, and ARCH-01-001 forbids a core dependency on any external system.
ARCH-05-003 MUST This codebase MUST discover connector plugins through Python entry points (importlib.metadata).

Each deployment installs a different set of connectors. Discovery through entry points lets a site add or remove a connector with no change to Vultron code.
Implements: ARCH-05-001
ARCH-05-002 MUST Connector plugins MUST translate only — no case handling logic, authorization, or case ledger management belongs in a connector.

A connector is an adapter: it translates between a tracker's format and Vultron domain types. Case logic, authorization and the case ledger belong in core, where one implementation serves every connector. If a connector holds any of them, two connectors can make different decisions for the same case, and a tracker becomes a way around the core rules. A CaseReader adapter's translated ledger is translation: it commits nothing, and the shadow does not store it (ADR-0191).
ARCH-05-004 MUST Besides its name, a connector plugin MUST implement at least one port the core declares for outside systems, such as CaseReader.

Outside systems differ in what Vultron does with them: the shadow only reads one case at a time, and the later gateway also writes. A single two-way interface forces a read-only connector to carry a write method it must not have. A connector that implements only the core ports it serves declares exactly what it does, and discovery can still tell what each plugin can do.
Refines: ARCH-05-003
ARCH-05-005 MUST NOT A connector plugin MUST NOT expose a method of a port the core declares for outside systems that it does not implement, including a stub that raises, logs or does nothing.

A stub write method is still a write path in the interface: a later change can fill it in without anyone noticing that the connector was meant to be read-only. If the method does not exist, adding a write path is a visible change to the ports the plugin declares.
Refines: ARCH-05-004
ARCH-05-006 MUST The connector loader MUST refuse an entry point that implements no port the core declares for outside systems, with an error that names the entry point.

A plugin that implements no port can do nothing, so loading it hides a packaging mistake. Naming the entry point lets the operator find the bad package.
Refines: ARCH-05-004

Core Object Hierarchy

ID Priority Requirement Related
ARCH-12-001 MUST NOT A wire-branch class MUST NOT inherit from a core class, other than one of core's AS2 base classes (ARCH-25-034). as_Base stands on pydantic.BaseModel directly, so the wire branch inherits no core field, configuration, or registration hook. A domain type's as_* name is an alias of its core class (ARCH-25-003), not a subclass of it.

If a wire class inherits from a core class, it also inherits core configuration and registration. A wire type can then register in a core registry, and the core root must stay lenient so that the wire class can parse loose inbound data. The wire base describes AS2 vocabulary that core does not model, and everything that core does model is the core class itself (ARCH-25-003). Core's AS2 base classes, AS2 models with no Vultron property, are the one exception (ADR-0208).
Refines: ARCH-25-004
See also: ARCH-25-003 — context for the reader
See also: ARCH-25-034 — names the core classes the exception admits
ARCH-12-002 MUST Every core model MUST descend from one of exactly two root classes. CoreRecord carries identity only (id_, type_, name). It is the base for internal records never serialized as AS2, such as dead-letter and offer records. CoreObject(CoreRecord) is the one AS2 object root. It declares every AS2 Object field, unused ones included (ARCH-25-008).

Some core types have an AS2 form, and others are internal records that never go on the wire. Two roots make this difference part of the type. The rendering port accepts a CoreObject and refuses a bare CoreRecord (ARCH-20-003), so an internal record cannot go into a delivered payload by mistake. A third level of root would add a distinction that no code uses.
Refines: ARCH-25-019
Refines: ARCH-25-008
ARCH-12-003 MUST Each core type MUST resolve extra="forbid" through its model_config, so that an unrecognised key raises and is not discarded.

Pydantic v2 ignores unknown keys by default. Without extra="forbid", a payload with an unknown key loses it with no error, and a participant's RM state can reset with no trace. The ban also catches typos, renamed fields and stale keys. A received activity reaches a core class only after parse_activity has handled its unknown keys, so the ban does not decide a peer's extension property (MV-11-004).
Depends on: ARCH-23-005 — ARCH-23-005 supplies the round-trip cleanups (computed-field stripping, wire-name keys) without which extra="forbid" rejects the project's own serialised output.
Implements: ARCH-25-025
ARCH-12-013 MUST Each CoreObject subclass MUST carry the AS2 field spelling as its own serialization form, through the alias_generator=to_camel it inherits from CoreObject (ARCH-25-002). A by_alias dump of a core object is thus its AS2 form.

One spelling on one class makes the dump of a core object its AS2 form. The rendering port can then be a plain dump (ARCH-20-002), with no second translation that can drift.
Refines: ARCH-25-002
Refines: ARCH-25-013
ARCH-12-014 MUST NOT Core types MUST NOT register in the wire VOCABULARY.

The wire VOCABULARY holds the classes for AS2 vocabulary that core does not model. If a core type registers there, a wire lookup can return a core class, and the wire and core registries no longer have disjoint keys (ARCH-23-002).
ARCH-12-015 MUST NOT Core types MUST NOT store @context as a serialized field. CoreObject.context_ stays exclude=True, and the by_alias serializer of CoreObject supplies @context once (VM-10-001).

@context belongs to the AS2 document, not to the stored state of an object. If a core type stores it as a field, the persistence dump carries it (ARCH-25-001), and nested objects can repeat it. One serializer that supplies it gives each AS2 form exactly one @context.
Implements: VM-10-001
ARCH-12-004 MUST NOT A wire-branch validator MUST NOT apply a rule that depends on case state or on stored data.

Rules about case state belong in core, where every reader of an object gets the same checks (ARCH-01-003) and the state they read is the receiver's own. A parse step sees one message, so a rule that needed stored data there would have to reach into the store from the wire layer, against the dependency direction. The as_* name of a domain type is its core class (ARCH-25-003), so the domain validators of that class already apply when it is read from the wire.
ARCH-12-021 MAY A wire-branch validator MAY refuse a message whose own form breaks a protocol rule, such as CP-01-012, SYNC-16-028, CM-11-011 or EMB-13-004.

A rule about the form of one message needs nothing but that message, so the parse edge can apply it and refuse the message once, with a clear reason, before any later step works on it (ADR-0032). A proposer that claims the CASE_MANAGER role (CP-01-012) or a Reject that names no object (SYNC-16-028) is malformed whatever the receiver holds.
See also: CM-11-011 — an example of a protocol rule a message's own form can break
See also: CP-01-012 — an example of a protocol rule a message's own form can break
See also: EMB-13-004 — an example of a protocol rule a message's own form can break
See also: SYNC-16-028 — an example of a protocol rule a message's own form can break
ARCH-12-008 MUST Wire-branch types MUST register in VOCABULARY.

The VOCABULARY registry is the wire layer's type-dispatch table; omitting a wire type prevents correct AS2 vocabulary lookup and object reconstruction.
ARCH-12-009 MUST CoreObject subclasses MUST register in CORE_VOCABULARY as the DataLayer primary reconstruction path.

CORE_VOCABULARY is used by _from_row() in SqliteDataLayer; every entry must be a CoreObject subclass to guarantee correct domain-object reconstruction from stored rows.
ARCH-12-010 MUST Each core type that extends CoreRecord but not CoreObject MUST register in CORE_TYPE_MAP, so that core code can find it by type string.

CORE_TYPE_MAP catches core records (e.g. VultronOfferRecord, VultronPendingCaseInbox) that carry domain state with no AS2 shape and so are not CoreObjects. Those types need a name-keyed lookup for core-layer and persistence callers.
ARCH-12-016 MUST NOT A wire-branch caller MUST NOT rely on CORE_TYPE_MAP as its path to resolve a type (VM-06-008).

The records in CORE_TYPE_MAP do not need to answer the type lookup of a wire-branch caller. A hit there is a coincidence of naming, not a wire counterpart.
Extends: ARCH-12-010
Derives from: VM-06-008
ARCH-12-011 MUST NOT Wire-branch types MUST NOT register in either core registry (CORE_VOCABULARY or CORE_TYPE_MAP).

Contaminating either core registry with wire types would allow wire-shaped objects to be reconstructed via find_in_vocabulary(), bypassing the CORE_VOCABULARY primary path and contradicting ARCH-12-014.
ARCH-12-006 MUST CoreActor and its subclasses MUST type the inbox and outbox fields as str, holding only the URI of the endpoint that the actor's profile states.

Domain logic only ever needs to route to the inbox URI. The full collection shape is an AS2 protocol concern, not a domain concern.
ARCH-12-017 MUST CoreActor MUST hold None for an inbox or outbox that the actor's profile leaves absent or blank, never an address derived from id_ (AKM-02-006).

An address derived from the id would be a value nobody asserted (ADR-0159). A hosted actor states its own endpoints when it is created, so its profile carries both, as ActivityPub requires. Delivery derives an inbox address only when none is held (OX-12-010).
Extends: ARCH-12-006
Refines: AKM-02-006
ARCH-12-018 MUST NOT Core-branch actor types MUST NOT carry the AS2 OrderedCollection wrapping of an endpoint.

The collection wrapping is a wire-only serialization concern. Core routes to the endpoint URI and needs nothing else from the collection.
Derives from: ARCH-12-006
ARCH-12-007 MUST Each protocol-significant core class, such as a case, report, participant or actor, MUST inherit from CoreObject, or from CoreRecord when it has no AS2 shape.

Consistent use of the core object hierarchy ensures that all protocol-significant domain objects share aligned field names, are rendered to AS2 form by the rendering port (ARCH-20-001) without per-type projection code, and are discoverable via CORE_VOCABULARY.
ARCH-12-019 MAY A core class MAY stay a plain BaseModel subclass when it holds only local configuration, a transient dispatch envelope or an internal record. The record qualifies only if it is never shared across the wire.

Such a class never goes on the wire and is never stored as a domain object, so the core object hierarchy gives it nothing but extra fields and registration.
ARCH-12-020 MUST Each plain BaseModel subclass under vultron/core/ MUST carry a docstring that says why it stays outside the core object hierarchy. A docstring inherited from a plain core base counts.

A plain BaseModel class is the exception, not the default. A stated reason shows that the choice was made on purpose, so a class does not leave the hierarchy by accident as the codebase changes.

Domain Model Richness Constraint

ID Priority Requirement Related
ARCH-09-002 MUST This codebase MUST define the actor domain models in vultron/core/models/: CoreActor and its subclasses VultronPerson, VultronOrganization, VultronService, VultronApplication and VultronGroup.

With the actor classes in core, core code uses them with no wire import, and the AS2 form of an actor is the serialization of its class (ADR-0211).
Refines: ARCH-09-001
ARCH-09-003 MUST NOT The wire layer (vultron/wire/as2/) MUST NOT define a second class for an actor domain model. Its as_Vultron* actor names alias the core classes (ARCH-25-003).

An actor has one class, its core class (ARCH-25-003). If the wire layer defines a second actor class, the two can drift apart, and code can use the wrong one.
Refines: ARCH-25-003

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-001 MUST A BT node's update() MUST return Status.FAILURE, not Status.SUCCESS, when a required blackboard key is absent or resolves to None.

Status.SUCCESS on a missing required input causes the BT sequence to continue as if the node succeeded, masking the failure and producing ledger gaps, dropped broadcasts, and mis-routed activities. See notes/domain-validation.md and ADR-0032.
ARCH-15-002 MUST A helper function that requires a non-None ID MUST check the result and raise VultronValidationError immediately. The strict guarantee lives in the caller or the helper itself — never deferred silently to downstream code.

Returning None from a helper that conceptually requires a valid ID moves the error from the point of failure to the point of use, making stack traces and logs point to the wrong location. See notes/domain-validation.md and ADR-0032.

Wire Vocabulary Object Naming Convention

ID Priority Requirement Related
ARCH-14-001 MUST All Vultron-specific wire vocabulary classes defined in vultron/wire/as2/vocab/objects/ MUST use the as_ prefix (e.g., as_VulnerabilityCase, as_CaseParticipant, as_CaseStatus). This extends the existing as_ naming convention — already applied to base ActivityStreams types (as_Activity, as_Actor, as_Object) — to all Vultron-specific wire objects in that package.

Without the as_ prefix, wire objects shadow identically-named core domain models, making it ambiguous which VulnerabilityCase a developer or agent is working with. The as_ prefix makes the layer boundary unambiguous at a glance and enables automated detection of violations.
ARCH-14-002 MUST The wire-layer base class for all Vultron-specific AS2 objects MUST be named as_VultronObject. This carries the as_ prefix ARCH-14-001 requires and drops the redundant "AS2" qualifier, since the prefix already connotes the wire layer.

Every other wire class has the as_ prefix (ARCH-14-001), so a base class without it breaks the convention that tells a reader which layer a class is in. The prefix already shows that the class is in the wire layer, so an "AS2" part in the name adds nothing.
Refines: ARCH-14-001
ARCH-14-003 MUST TypeAlias companion types (wire-layer reference unions, e.g., VulnerabilityCaseRef) MUST also use the as_ prefix (e.g., as_VulnerabilityCaseRef, as_CaseParticipantRef).

Companion aliases that do not follow the as_ naming convention undermine the goal of ARCH-14-001: an import of VulnerabilityCaseRef is just as ambiguous as importing VulnerabilityCase from the wire layer.

DataLayer Scope Contract

ID Priority Requirement Related
ARCH-13-003 MUST This codebase MUST open a DataLayer under the actor's canonical URI, actor.id_, never under a short ID, a URL path segment or another derived identifier.

Each actor has its own store, and the actor identity selects the store (ADR-0073). If two spellings of one actor identity reach the store factory, they open two different stores. Data written under one spelling is then missing under the other, and the actor reads an empty store. The canonical URI is the one spelling that every component knows.
ARCH-13-006 MUST A driving adapter MUST resolve a path segment in a request to the actor's canonical URI before it opens the store.

A request names an actor by a path segment, which is not the canonical URI. The store factory then gets a second spelling of the actor identity unless the adapter resolves it first (ADR-0073).
Implements: ARCH-13-003

App State Isolation

ID Priority Requirement Related
ARCH-16-001 MUST NOT create_app(), or any equivalent application factory, MUST NOT change module-level singletons, global registries or process-wide shared state.

Tests and demos call create_app() more than one time in one process. If the factory changes module-level state, each new app inherits the changes that the first app made, and the tests are not isolated. This applies to vocabulary registries, DataLayer factories, BT bridges, actor caches and every other mutable global.
ARCH-16-002 MUST create_app() MUST scope all per-application state to the app instance it returns or to the lifespan context of that app.

Each app then owns its own state. A second app in the same process starts clean, and the state of an app goes away with it.
Extends: ARCH-16-001

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-002 MUST The rendering port's adapter MUST produce its output as the core object's own model_dump(by_alias=True, exclude_none=True, mode="json", serialize_as_any=True), with no field-name translation of its own.

A second translation path could only drift from the class's own spelling, the defect ADR-0063 removes. serialize_as_any=True renders nested values by runtime type, as every other AS2 path does; without it an inline wire object holding an undeclared value type (an IRI inbox) is a serializer warning, not a rendering (#3930).
Extends: ARCH-20-001
ARCH-20-010 MUST NOT The rendering port's adapter MUST NOT resolve a wire counterpart, through WIRE_TYPE_MAP, a pairing registry or a from_core() projection.

Under one object model the core object is its own wire form (ARCH-25-001), so a counterpart lookup has nothing to find.
Extends: ARCH-20-002
ARCH-20-003 MUST The rendering port MUST raise VultronValidationError for an object with no AS2 shape, and not return None, a core-shaped dump or a partial rendering. An object has no AS2 shape when it is not a CoreObject, such as a bare CoreRecord like an offer or dead-letter record. A missing separate wire class is not a failure.

A payload snapshot in core shape cannot be rebuilt by a receiver (CLP-07-011), and at the call site it looks the same as a correct one. An error raised at once shows the problem where it starts (ARCH-15-002). The CoreObject check stops a bookkeeping record such as VultronOfferRecord from going into a delivered payload. Each core type is its own wire form, so a missing wire class is not a reason to refuse.
ARCH-20-004 MUST This codebase MUST inject the rendering port into behavior-tree execution as it injects sync_port. That is a BTBridge constructor parameter, published to the blackboard under a named key.

Consistency with SyncActivityPort keeps one injection idiom for driven ports.
Extends: ARCH-20-001
ARCH-20-011 MUST NOT BT nodes and use-case helpers MUST NOT import an adapter directly or build a default renderer.

An import-time default would bring back the core→wire import that the port exists to prevent (ARCH-01-001).
Extends: ARCH-20-004
ARCH-20-005 MUST Core-branch types MUST NOT declare a to_json(), to_wire(), or similarly-named method that emits wire-shaped output. Rendering is the port's responsibility, not a method on the domain object.

A rendering method on a domain object is always available, so any code that needs camelCase output can call it and go around the port. The port then stops being the one place that decides what goes on the wire (ARCH-20-001).
Refines: ARCH-20-001
ARCH-20-006 MUST A driving adapter MUST serialize each AS2 document it serves over HTTP from an AS2 class. An AS2 document is an application/activity+json response, such as GET /actors/{id}. An AS2 class is a CoreObject subclass, which is its own wire form (ARCH-25-003), or an as_Base wire vocabulary class. A by_alias dump of any other model, a bare CoreRecord included, is not an AS2 document.

A domain type has one class, so the AS2 form of a core actor or case is that class's own by_alias dump; there is no separate as_* class to route through. What still varies is whether a model has an AS2 shape at all. A CoreObject inherits the alias_generator and the @context serializer, and test_promoted_core_classes_are_exactly_as2_representable holds every subclass to a complete set of AS2 spellings. A bare CoreRecord such as VultronOfferRecord inherits neither, so dumping it by alias emits snake_case bookkeeping keys with no @context under an AS2 content type, which a peer cannot read. This is the HTTP edge's counterpart of the rendering port's CoreObject gate (ARCH-20-003).
Uses definition from: ARCH-25-003
ARCH-20-007 MUST NOT Core code MUST NOT normalise a wire object into its core counterpart by dumping it with by_alias=True and revalidating through the core class ("dump-and-revalidate").

The dump of a wire object holds the keys that the wire class emits, and the core class does not always declare them. Under extra="forbid" (ARCH-12-003), a key with no core field raises. Without it, the key is lost and gives no error. Either way, the result depends on which keys the two classes happen to share, not on a defined rule. rehydrate() and project_wire_snapshot_to_core are the defined paths (ARCH-20-008, ARCH-20-009).
ARCH-20-008 MUST Core code MUST treat a core-branch instance of an inbound nested object as already canonical, and never duck-type a projection on it, such as getattr(obj, "to_core", None).

A domain type has one class (ARCH-25-003), so no object that core holds has a to_core() method. A duck-typed lookup for it always returns None, and the branch behind it is dead code that a reader can take for a live fallback. The ban also stops code from a second route to dump-and-revalidate (ARCH-20-007).
Extends: ARCH-20-007
Derives from: ARCH-25-003
ARCH-20-012 MUST Core code MUST rebuild an object from a snapshot dict only through project_wire_snapshot_to_core (vultron/core/models/_helpers/inbound.py).

rehydrate() turns an ID into an object (VM-06-007), and the snapshot helper turns a dict into an object, so each case has one defined path.
Extends: ARCH-20-008
ARCH-20-009 MUST Core MUST get a nested object named only by reference from the DataLayer port (DL-05-001), never by dump-and-revalidate or a fabricated placeholder. A reference is a bare IRI, a typed reference (MV-10-011) or a stub. Core gets the object as rehydrate() resolved it at ingress (VM-06-007), or by reading it back.

The DataLayer port returns core objects that already passed validation, so a second derivation in core is not necessary. A derivation by dump-and-revalidate is also the idiom that ARCH-20-007 forbids. A fabricated placeholder states facts that no actor asserted. The store is thus the only source for an object that a message names only by reference.
Refines: ARCH-20-007
Uses definition from: DL-05-001
See also: VM-06-007 — context for the reader
See also: MV-10-011 — defines the typed reference, one form a reference takes

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-004 MUST NOT A mode="after" model validator on a core model under vultron/core/ MUST NOT assign to self. Wire-layer validators are exempt, because the wire branch never enables validate_assignment (ARCH-21-003) and so cannot re-enter.

validate_assignment runs every mode="after" validator again on each assignment, so a validator that writes to self calls itself again. A guarded validator stops at depth 2, but an unguarded one recurses until the stack is full. The RecursionError then hides every real type failure.
See also: ARCH-21-003 — context for the reader
ARCH-21-006 MUST A core model MUST derive a value from its other fields in a mode="before" validator, where the derived value is itself validated.

A write through self.__dict__ prevents the recursion of ARCH-21-004, but it leaves the derived value unvalidated. A mode="before" validator derives the value before validation, so the value is validated.
Extends: ARCH-21-004
ARCH-21-005 SHOULD An architecture test SHOULD enforce ARCH-21-001, ARCH-21-003 and ARCH-21-004.

These rules are about the shape of the code, so a scan of the code can check them on every test run, where a review can miss a new violation.
Verifies: ARCH-21-001
Verifies: ARCH-21-003
Verifies: ARCH-21-004
ARCH-21-007 SHOULD The ARCH-21-005 test SHOULD list each remaining known violation in an exact set. The set then fails when it grows and when a listed violation is fixed but not removed.

An exact set fails when it grows and when a fixed entry stays in it, so it makes drift visible.
Extends: ARCH-21-005
ARCH-21-008 SHOULD Each such backlog SHOULD have a companion xfail(strict=True) goal test, so that emptying the backlog fails the build and forces the marker to be deleted.

A strict=False xfail continues to pass after the work is done. It never shows that it can be removed, and it gives no signal of partial progress. A strict goal test fails when the set is empty, so the marker must then be deleted, and completion is visible.
Extends: ARCH-21-007
ARCH-21-009 MUST Each scan of the ARCH-21-005 test MUST complete within one second.

The time limit keeps the scan cheap enough to run in every test run.
Extends: ARCH-21-005

Wire→Core Import Boundary Enforcement

ID Priority Requirement Related
ARCH-22-001 MUST NOT Modules under vultron/wire/ MUST NOT import anything under vultron/core/ except vultron/core/models/ and vultron/core/states/. The forbidden set includes behaviors/, use_cases/, ports/, services/, predicates/, scoring/, case_states/, participants/, dispatcher.py and sync_helpers/. The permitted set is an allow-list, so a package added to vultron/core/ later is forbidden until this requirement admits it. A TYPE_CHECKING-guarded import is exempt, because it is erased at runtime and can only appear in an annotation.

AS2 is a serialization of the core object model, so the wire layer must name the classes that it serializes and the states that they carry. Hexagonal dependencies point inward, so the import that breaks the architecture is core to wire (ARCH-01-001), not this one. Core behavior must still stay out of the wire layer: if wire code calls a use case or a service, the wire layer cannot be replaced as one unit (ARCH-06-001). An allow-list makes each new core package forbidden until a person decides to admit it.
Refines: ARCH-25-006
ARCH-22-002 MUST An architecture test MUST enforce the ARCH-22-001 allow-list over every module under vultron/wire/.

An allow-list that no test checks drifts as soon as one import slips in. A scan of every wire module catches each import that the allow-list does not admit.
Verifies: ARCH-22-001
ARCH-22-004 MUST The ARCH-22-002 test MUST detect an import deferred into a function body, as well as a top-level one.

Checking only module-level imports would miss a deferred import in a function body, which is a runtime dependency like any other.
Extends: ARCH-22-002
ARCH-22-005 MUST The ARCH-22-002 test MUST key its scan on the importing directory, vultron/wire/, not on a blessed importing location.

A rule phrased as "only this location may import core" is evaded by moving a file. Keyed on vultron/wire/, the rule follows the code.
Extends: ARCH-22-002
ARCH-22-006 MUST The ARCH-22-002 test MUST state the permitted set as an allow-list, not as a list of forbidden packages or of known violations.

A deny-list admits a newly added core package by default, which is the failure mode an allow-list removes.
Extends: ARCH-22-002
ARCH-22-003 SHOULD NOT The wire→core boundary test SHOULD NOT carry a KNOWN_VIOLATIONS set or a companion goal test.

The boundary from wire to core is already clean under the ARCH-22-001 allow-list. The test thus states an invariant and needs no target to converge on, and a violation set or an xfail marker would have no work to do.
ARCH-22-007 SHOULD NOT A goal test SHOULD NOT assert a state that other requirements make unreachable.

An unreachable goal invites an implementer to break a MUST so that the test passes. That is worse than no goal test.

Core↔Wire Vocabulary and Round-Trip Invariants

ID Priority Requirement Related
ARCH-23-002 MUST Wire vocabulary registration keys in VOCABULARY MUST be distinct from core vocabulary keys in CORE_VOCABULARY so that no wire class shadows a core type.

If a wire class and a core class register under the same key, a lookup by that key can return the wrong class, and stored or received data can be rebuilt as a wire object. Disjoint keys keep each lookup unambiguous. They also stop a new wire class from shadowing a core type with no notice. See ADR-0211.
ARCH-23-003 MUST NOT Serialized AS2 output MUST NOT change as a result of a vocabulary-key change. The wire "type" value emitted on the wire is independent of the registry key under which a wire class is registered.

The registry key is an internal lookup value. The type value is a commitment to receivers, which match on it. If a change to a key changes the output, a change inside Vultron breaks peers that did not change. The key and the wire value differ: the code derives the key from the class name (as_Create), which is not the type value (Create) (VM-01-004).
ARCH-23-004 MUST This codebase MUST derive the set of AS2 reference-typed fields from the wire classes' type annotations, not restate it as a hand-maintained collection.

The as_ObjectRef annotations already state which fields hold references. A hand-kept list states the same fact a second time. A second statement can drift from the annotations with no notice, and a field then serializes or persists in the wrong form. A set derived from the annotations stays correct when a field changes.
ARCH-23-008 MUST NOT A translation path MUST NOT open-code a per-field reference collapse.

A reference collapse written into each translation path states again which fields hold references. That copy can drift from the annotations, and a field then serializes or persists in the wrong form.
Extends: ARCH-23-004
ARCH-23-005 MUST A serialize-then-validate round trip on a core object MUST reproduce that object, on the persistence record round trip as well as in translation.

The project must read back what it writes, both from its own store and from the AS2 form it sends.
ARCH-23-009 MAY Serialization MAY emit a computed field, such as VulnerabilityCase.activeParticipants on the AS2 by_alias path only, because CM-31-014 forbids storing it.

A computed field gives a reader a value it would otherwise derive itself. It is derived from stored state, so emitting it adds nothing that can disagree with a correct object.
See also: CM-31-014 — a cited rationale ("because CM-31-014 forbids storing it")
ARCH-23-010 MUST Validation MUST discard a supplied computed-field value that equals the value derived from the object's own state.

A computed field in a dump is a key that the model does not store, and extra="forbid" (ARCH-12-003) refuses an unknown key, so validation needs a rule for it. A correct producer always emits a value that agrees with the state, so validation can discard it safely.
Extends: ARCH-23-005
ARCH-23-011 MUST Validation MUST refuse a supplied computed-field value that contradicts the value derived from the object's own state, and not discard it.

A value that contradicts the state cannot come from a correct producer, and a derived value that gates disclosure must fail closed. Validation thus refuses it and does not discard it.
Extends: ARCH-23-005
ARCH-23-012 MUST Serialization MUST emit the wire-facing key names id, type and @context, not the Python field names id_, type_ and context_.

Receivers use the wire key names (id, type, @context), and stored rows use id and type (ARCH-25-001). A dump that emits Python field names thus matches neither.
Extends: ARCH-23-005
ARCH-23-006 MUST Each core class that a wire-branch annotation names for a protocol-significant message slot MUST be exactly AS2-representable. That is, each field it carries has a valid AS2 property spelling (ARCH-12-013), and it carries no field that cannot go on the wire.

A class in a message slot goes on the wire as part of the message. If it has a field with no valid AS2 spelling, its AS2 form shows a Python name that a peer cannot read, or the class carries data that cannot be sent. Message slots name core classes directly (ARCH-25-003), so each such core class must be exactly AS2-representable. A core guard inside a wire union must fail only its branch of the union, so VultronValidationError inherits ValueError.
Depends on: ARCH-12-013
Refines: ARCH-25-016
ARCH-23-007 MUST An actor endpoint collection built from a URI MUST carry no published or updated timestamp. Such a collection is the inbox or outbox OrderedCollection around the address the actor's profile states.

An endpoint built from a URI is an address, not an object that this process authored, so it has no creation time (ADR-0103). The core actor keeps only the URI (ARCH-12-006). If each read builds the collection with a clock stamp, a stored actor reads back unequal to itself when a second passes between the write and the read.
Extends: ARCH-12-006
ARCH-23-013 MUST This codebase MUST carry a timestamp that arrives on an inbound actor endpoint collection as received.

An inbound stamp is a claim of the sender, so the receiver keeps it as received (ADR-0103).
Extends: ARCH-23-007

One Object Model; AS2 Is a Serialization of It

The decision-level rules of the one-object model: the core classes are the object model, and the ActivityStreams 2.0 (AS2) wire format is one of two ways those same classes are written out. Each requirement here states one consequence of that decision in full, so a reader needs no decision record to know the rule. Finer-grained requirements in ARCH-12, ARCH-20, ARCH-22, ARCH-23, SDO-01, MV-11 and VM-06 refine these; where one does, the statement it refines names it.

ID Priority Requirement Related
ARCH-25-001 MUST The classes under vultron/core/models/ MUST be the one object model, so no second set of classes models the same domain concept. A core object is written out in one of the two ways that ARCH-25-011 and ARCH-25-012 state, chosen by where it is going.

Two class hierarchies for one domain concept need translation code between them, and that code drifts each time one side changes. A core concept and its AS2 form have the same fields with the same meaning, so one set of classes can carry both. A received activity is also kept as received evidence (VM-08-002, CLP-07-011); that copy is neither of the two serializations.
ARCH-25-011 MUST For inter-actor delivery over HTTP, this codebase MUST write a core object as AS2 through a by_alias=True dump, which emits camelCase field names and @context. AS2 is the HTTP transmission format only.

The destination selects the serialization. Peers read AS2, so delivery to them uses the AS2 form of the class.
Extends: ARCH-25-001
ARCH-25-012 MUST For persistence to the data layer, this codebase MUST write a core object by model_dump(mode="json") without by_alias, then _rekey_wire_identity(). That step renames only id_, type_ and context_ to id, type and @context, so no other stored field takes its AS2 spelling.

The data layer stores a plain dump with renamed identity keys. Only the identity keys need the wire spelling, because stored rows are found by id and type.
Extends: ARCH-25-001
ARCH-25-002 MUST Each core field MUST have a Python-convention name (in_reply_to, not inReplyTo), with its AS2 spelling in its Pydantic alias. This codebase builds no parallel core-only naming scheme.

Pydantic aliases already separate the Python spelling from the AS2 spelling, so a second naming scheme adds nothing.
ARCH-25-013 MUST The aliases MUST come from the alias_generator=to_camel declared once on CoreObject and inherited by every subclass, not enumerated per field or declared per class. An explicit alias is required only where the generator cannot produce the AS2 name. These are id_, type_ and context_, since no generator yields @context. They also include a field whose name differs from its AS2 property, such as the status dimension field rm, spelled rmState. ARCH-12-013 refines this.

If each class declares its own alias generator, one class can omit it and send attributed_to on the wire while its siblings send attributedTo. A peer then cannot read the payload, and nothing shows the error before that. One generator on CoreObject, inherited by every subclass, gives every class the same spelling rule.
Extends: ARCH-25-002
ARCH-25-014 MUST NOT Core code MUST NOT type an AS2 spelling.

A spelling typed in core logic is a second copy of the alias. It drifts when the alias changes, and core then reads or writes a key that the class no longer uses.
Extends: ARCH-25-002
ARCH-25-003 MUST A domain type MUST have exactly one class, its core class. A wire-facing as_* name for a domain type is thus an alias of the core class, not a separate or derived class, so as_VulnerabilityCase is VulnerabilityCase.

When a wire class and a core class model the same concept, code can use one in place of the other, and data can be misread. One class for each domain type makes that mistake impossible.
Satisfies: PRM-04-001
ARCH-25-015 MUST Message-shape classes MUST name core classes in their object slots (object_: VulnerabilityReport, target: VulnerabilityCase).

A slot that names a core class carries the one class of that domain type, so core code reads the object it gets with no projection step.
Extends: ARCH-25-003
ARCH-25-016 MUST A core class that can appear in a message slot MUST be exactly AS2-representable. Each field it carries has a valid AS2 property spelling, and it carries no field that cannot go on the wire (ARCH-23-006). A core class that never appears in a message is not constrained by AS2.

A class in a message slot goes on the wire, so it must be exactly AS2-representable. Records that never go on the wire, such as dead letters, pending-queue entries and offer records (CoreRecord subclasses), stay free of AS2 limits.
Extends: ARCH-25-003
ARCH-25-017 MUST NOT Core code MUST NOT look for a to_core() projection on an object it holds. With one class there is nothing to project.

A lookup for a projection that cannot exist is dead code, and a reader can take it for a live fallback.
Derives from: ARCH-25-003
ARCH-25-004 MUST NOT The wire and core hierarchies MUST NOT share a root, other than one of core's AS2 base classes (ARCH-25-034). ARCH-12-001 refines this.

A shared root makes the wire branch inherit core configuration and registration. It also forces the core root to stay lenient so that the wire branch can parse loose inbound data. The wire and core branches have nothing to share (ARCH-12-001). Separate roots let core stay strict while inbound wire data stays lenient. Core's AS2 base classes are the one shared ground: they are AS2 models that both layers use (ADR-0208).
See also: ARCH-25-034 — names the core classes the exception admits
ARCH-25-018 MUST as_Base MUST stand directly on pydantic.BaseModel and carry the AS2 envelope fields.

A wire root on pydantic.BaseModel inherits no core configuration or registration hook, so the wire branch stays lenient for loose inbound data.
Implements: ARCH-25-004
ARCH-25-019 MUST Core MUST have exactly two roots. One is a minimal record base carrying identity only (id_, type_, name) for records that are not AS2 objects, such as dead letters. The other is one object root carrying the AS2 object fields, @context and required timestamps. ARCH-12-002 refines this.

Some core types are AS2 objects, and others are internal records that never go on the wire. Two roots let the type show that difference, and keep core strict on its own root.
Extends: ARCH-25-004
ARCH-25-005 MUST A status dimension object MUST write itself as its bare state value and read that bare value back, so RmDimension writes "START" and accepts "START". SDO-01-004 refines this.

A dimension object holds one data field, state. All its other members are behavior, and behavior does not serialize, so the bare state value is the full data of the object. When the dimension writes the bare value, its core form and its wire form are the same.
ARCH-25-020 MUST Each status dimension class MUST declare its own serializer and reader, not leave them to a helper or a translator.

A serializer and a reader on the class keep the rule in one place, so every path that dumps or reads a dimension gets the same form.
Implements: ARCH-25-005
ARCH-25-021 MUST NOT The bare-value form MUST NOT change the AS2 wire form, since the enclosing field's alias (rmState) carries the spelling.

The alias of the enclosing field keeps the published AS2 form unchanged for peers.
Extends: ARCH-25-005
ARCH-25-006 MUST NOT The wire layer MUST NOT import anything under vultron/core/ except the core object model (vultron/core/models/) and its state enumerations (vultron/core/states/). ARCH-22-001 names the forbidden packages.

Hexagonal dependencies point inward: outer layers depend on inner layers (ADR-0009). The wire layer is outside core, so it may name the core types that it serializes. Core behavior must stay out of the wire layer, so that the wire layer stays replaceable as one unit.
ARCH-25-022 MUST This codebase MUST express the ARCH-25-006 rule as an allow-list attached to the importing directory. Moving a file then cannot evade it, and a new core package is forbidden by default.

An allow-list keyed on the importing directory still holds when a file moves, and it forbids a new core package until a person admits it.
Implements: ARCH-25-006
ARCH-25-023 MUST NOT Core MUST NOT import wire (ARCH-01-001).

Hexagonal dependencies point inward, so the inner layer never depends on the encoding that an outer layer chose (ADR-0009).
Refines: ARCH-01-001
ARCH-25-007 MUST This codebase MUST decide each unrecognised key on inbound data at the parse edge, parse_activity, by one rule for every object at every depth. A near miss for a declared spelling refuses the whole activity and names both spellings. Any other unknown key is set aside and reported once at INFO (MV-11-001 to MV-11-003). The report carries activity_id, the sender's actor_id, the field path and the key, and the activity proceeds on its declared fields.

A key that spells a field Vultron reads was meant as that field. If Vultron continues without it, it loses data and gives no error, so a near miss refuses the activity. A key that Vultron does not read can be an extension of a peer, so Vultron reports it and does not refuse or lose the activity (ADR-0086). One rule in parse_activity, for every object at every depth, gives the same result whatever class an object resolves to.
ARCH-25-033 MUST NOT The class an object happens to resolve to MUST NOT decide an unrecognised key on it.

One rule in parse_activity gives the same result whatever class an object resolves to. Were the class to decide, the same key would be set aside in one position and refuse the activity in another, and a peer could not predict either.
Extends: ARCH-25-007
ARCH-25-034 MUST Each AS2 base data class that core holds (an AS2 base type such as Object or Collection) MUST be defined in vultron/core/models/ and registered in AS2_BASE_CLASSES; the wire's name for it is an alias of the core class or a thin subclass of it.

Core owns the AS2 base vocabulary, so a core rule about an AS2 type reads that type's own class, and no copy of its names or fields is kept elsewhere. Core still never imports the wire (ARCH-01-001); the wire imports core's models (ARCH-22-001).
ARCH-25-035 MUST Each class in AS2_BASE_CLASSES MUST model an AS2 type as the AS2 Activity Vocabulary defines it: its type value and serialized property names are AS2's, each property is one the AS2 ontology allows on that type, it carries no Vultron property, and on receipt it requires nothing AS2 does not require beyond the recorded Vultron receive rules (OID-01-013, CLP-15-011).

The base classes are shared by core and the wire only while they stay AS2 models. A Vultron property, a renamed property or an extra requirement on one would reach every peer, and a valid AS2 object from a peer would no longer validate.
Refines: ARCH-25-034
See also: OID-01-013 — a recorded receive departure the check allows
See also: CLP-15-011 — a recorded receive departure the check allows
ARCH-25-024 MUST Reading MUST be strict on declared fields, so the edge refuses a recognised field whose value violates its declared type.

A declared field with a value of the wrong type is a defect of the sender. Read as a default or as absent, it would hide the defect and change protocol state with no trace.
Extends: ARCH-25-007
ARCH-25-025 MUST Every core class MUST reject an unknown key in in-process and stored data, where one is always a bug. The CoreObject base keeps extra="forbid" (ARCH-12-003), and no core class adds a loose extras field. Inbound data enters only through the parse edge (MV-11-004).

Inside the process an unknown key is always a bug, so CoreObject keeps extra="forbid". A loose extras field would let such a key pass with no error.
Extends: ARCH-25-007
ARCH-25-026 MUST NOT The parse edge MUST NOT carry a set-aside key on the parsed object, so the received evidence (VM-08-002) is its only copy.

A set-aside key on the parsed object would go on into core and the store, where extra="forbid" refuses it. The received evidence already keeps it for a reader who needs it.
Extends: ARCH-25-007
Uses definition from: VM-08-002
ARCH-25-008 MUST This codebase MUST declare every legitimate AS2 object and activity field on the core roots and on the wire as_Object base. That includes fields Vultron does not use, such as bto, bcc, icon and image. A recognised but ignored field is thus structurally distinct from an unknown one, and only an unknown key reaches the parse-edge partition of ARCH-25-007.

A field that is declared but not used is known and can be ignored, so only a key that is truly unknown reaches the near-miss check.
Extends: ARCH-25-007
ARCH-25-027 MUST A near-miss refusal MUST name the arriving key and the declared spelling it resembles.

The refusal names both spellings, so the sender can correct the key.
Extends: ARCH-25-008
ARCH-25-028 MUST The parse edge MUST find a near miss only by MV-11-002's normalisation, never by a similarity measure such as edit distance. That normalisation lowercases a key and removes every non-alphanumeric character.

AS2 has many short property names that are one character apart, so an edit-distance measure would give many false matches. A fixed normalization gives a deterministic answer.
Extends: ARCH-25-008
Uses definition from: MV-11-002
ARCH-25-009 MUST An object slot MUST hold the whole object, not an ID, once read. This is a prototype shortcut: it MUST NOT be read as a permanent architectural principle, and MUST be revisited before production.

An embedded copy only delays the work of normalizing the data. It does not do that work. A production system is expected to use references, one backing store, and join objects where a relationship carries its own data.
ARCH-25-029 MUST rehydrate() in vultron/wire/as2/rehydration/ MUST be the sole owner of ID-to-object materialisation, and resolve a reference through the DataLayer it is given.

rehydrate() holds the data layer, so it can resolve the real object. One owner gives every slot the same resolution rule.
Extends: ARCH-25-009
ARCH-25-030 MUST rehydrate() MUST read off the slot's declared type whether an unresolvable reference is deferred or refused. A slot that admits str (every ActivityStreamRef[T]) keeps the IRI (VM-06-004), and a slot that admits a model and no str refuses (VM-06-007).

The slot type already says whether an IRI is allowed, so the rule for an unresolved reference needs no second source.
Extends: ARCH-25-029
See also: VM-06-004 — a pointer to where the outcome for that slot is stated
See also: VM-06-007 — a pointer to where the outcome for that slot is stated
ARCH-25-031 MUST NOT This codebase MUST NOT fabricate a placeholder object, an actor included, for an unresolved reference.

A placeholder or a synthesized actor states facts that no actor asserted, and activity can then be attributed to the wrong actor.
Extends: ARCH-25-029
ARCH-25-010 MUST This codebase MUST keep the AS2 vocabulary and the formal protocol message set as separate artifacts, neither derived as a subset of the other. The mapping between them reconciles them: MessageSemantics and the semantic registry, described in notes/message-type-reference.md.

AS2 can express more sentences than Vultron needs. The formal protocol has the opposite problem: it treats two messages as one. To propose an embargo and to propose a revision of one are the same sentence with different start and end states. Neither list is thus a subset of the other, and the mapping between them reconciles them (ADR-0083).
ARCH-25-032 MUST The message-shape classes, which subclass AS2 activity verbs, MUST live under vultron/wire/.

A message-shape class is the AS2 encoding of a message, not its identity, so it belongs in the wire layer.
Extends: ARCH-25-010

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

BT Execution Model

ID Priority Requirement Related
BT-01-001 MUST BT execution MUST be event-driven, triggered by handler invocation

Case state changes only when an event occurs: a received message or a local trigger. A tree that runs on any other cue can change state with no activity to record, attribute or answer for.
BT-01-002 MUST BTs MUST execute to completion (or max iterations) per invocation

The bridge keeps no tree between requests, so a tree that stops part of the way loses its place. Each tree runs to completion. An iteration limit stops a node that never settles. Thus every request gets a known result.
BT-01-003 MUST NOT BT execution MUST NOT use continuous tick-based polling loops

A polling loop needs a long-lived process that ticks trees between messages, and this design has no place for that process. A polling loop also does unnecessary work, and it can change state with no event to answer for. Event-driven runs (BT-01-001) cover every case that the protocol needs.
BT-01-004 MUST BTs MUST be single-shot executions within handler context

A tree that runs once inside the handler call uses the same store, actor and error handling as that call. Thus the result of the tree is the result of the handler. A tree that continues after the handler returns acts after the inbox outcome is already set.

BT Library

ID Priority Requirement Related
BT-02-001 MUST Prototype handlers MUST implement BT execution using an industry-standard BT library.

Mature libraries provide visualization, debugging, and standard BT semantics
BT-02-002 MUST Simulation code in vultron/bt/ MUST remain unchanged

New trees are checked against the legacy simulator in vultron/bt/ (BTC-01-002). If you change the simulator to suit new code, you remove the reference that it keeps. You also put the demos and tests of the simulator at risk, with no gain for the protocol.

State Management

ID Priority Requirement Related
BT-03-001 MUST BTs MUST use DataLayer as persistent state store

The DataLayer is the only state that continues after a tree run, and the only state that other components read. If a tree keeps state in a different location, that state is lost when the run ends, or it does not agree with the store.
BT-03-002 MUST NOT BTs MUST NOT maintain separate blackboard persistence

A second persistent copy of state on the blackboard gradually becomes different from the DataLayer. Then one question has two answers. Blackboard storage is process-global, so persisted values also go from one run into the next (BT-17-003).
BT-03-003 MAY BT blackboard MAY cache DataLayer state during execution

A node that reads the same object many times in one run causes unnecessary store reads. A cache that exists only for that run stays close to the store, because every write still goes to the store (BT-03-001, BT-03-004).
BT-03-004 MUST State changes MUST be committed to DataLayer on successful execution

A successful run shows that the protocol step occurred. If the run does not save its changes, the actor reports the step as done, but its store still shows the earlier state. Then peers act on a step that the actor does not record.

Handler Integration

ID Priority Requirement Related
BT-04-001 MUST A received-side handler MUST keep its use-case class contract when its work moves into a behavior tree. That contract is __init__(dl, request), an execute() that returns a HandlerResult, and routing by semantic-type key in use_case_map().

When the work inside a handler moves into a tree, the path of messages to the handler must not change. A fixed handler contract keeps the dispatcher, the routing table and the current tests the same while the internal parts of the handler change.
BT-04-002 MAY Handlers MAY invoke BTs via bridge layer

A bridge gives every handler one procedure to set up and run a tree. Thus each handler does not repeat the setup of the store, the actor and the blackboard.
BT-04-003 MUST Handlers MUST remain synchronous (BT execution within handler)

The inbox runs handlers outside the request path (BT-11-002), so a synchronous handler does not delay the HTTP response. When the tree runs inside that synchronous call, the run finishes and its errors show before the handler returns.
BT-04-004 MUST BT execution errors MUST propagate to handler error handling

If an error stops at the tree, the handler reports success for a step that failed. When the error goes up to the caller, the inbox outcome and the logs show the failure.

BT Bridge Layer

ID Priority Requirement Related
BT-05-001 SHOULD System SHOULD provide BT execution bridge for handler-to-BT invocation

The bridge is the one connection between handlers and trees. With one bridge, the code for locking (BT-11-004), blackboard cleanup (BT-17-007) and failure reports (BT-13-001) exists once for every tree. Thus it cannot be different between handlers.
BT-05-002 SHOULD Bridge SHOULD set up py_trees context with DataLayer access

Nodes read and write through the DataLayer (BT-03-001). When the store is on the blackboard, every node in a tree gets the same store, and no node must receive it separately.
BT-05-003 SHOULD Bridge SHOULD populate blackboard with activity and actor state

Nodes need the activity that the tree processes and the identity of the actor that runs the tree. When both are on the blackboard, every node in the tree has the same view of the request.
BT-05-004 SHOULD Bridge SHOULD execute tree and return execution result

The caller uses the outcome of the tree to set its own result and to report why a run failed (BT-13-001). The bridge returns the outcome, so callers do not tick trees or read the internal parts of trees.
BT-05-005 MUST A behavior tree's blackboard datalayer MUST be the store of its blackboard actor_id.

With per-actor storage, each store belongs to one actor. Thus the identity of the executing actor selects the store that the tree uses. If the store and the actor on the blackboard do not agree, a tree that emits for the Case Actor can create an activity in one store and queue it in the outbox of a different actor. Then the Case Actor never delivers the activity, and its outbox names an activity that its own store does not hold. The bridge makes the store and the actor agree one time. Thus every node writes to the correct store, and each caller does not have to supply a matching DataLayer. A fix only at the trigger is not sufficient. Store isolation must not depend on each caller doing the correct thing, in the same way that it must not depend on each query using a filter. If the store authority does not host the actor_id, no store is available to agree with. Thus the bridge raises an error and does not run the tree in the store of the requester. A participant whose container does not host the CASE_MANAGER sends a message to it (CM-24-004, ADR-0109).
Uses definition from: DL-07-001
Extends: BT-05-002
BT-05-007 MUST The bridge MUST make the blackboard datalayer agree with the blackboard actor_id, and not take the store that the caller injected as given.

Store isolation must not depend on each caller supplying the matching store, in the same way that it must not depend on each query using a filter. When the bridge makes the two agree one time, every node writes to the store of the executing actor. A store authority that does not host the actor_id has no store to agree with, so the bridge raises and does not run the tree.
Implements: BT-05-005
BT-05-006 MUST The executing actor of a role-gated tree MUST hold the gating role.

These are three separately-specified identities, and letting any two drift produces a silent skip rather than an error: the gate evaluates against an actor that holds no role, returns SUCCESS-by-skip, and nothing is written. This is the invariant that made the delegated-emit defect class possible in the first place. Stated as a MUST rather than a note because production satisfying it today is not the same as it being required — without one, a future BT node can re-separate the three identities and the failure mode is again a silent skip. A static architecture ratchet was considered and rejected: role holding is data-dependent, so a check could only approximate it and would be noisy.
Constrains: CLP-09-001
BT-05-008 MUST The store of a role-gated tree MUST belong to the tree's executing actor.

If the store belongs to an actor other than the one the gate checks, the tree reads and writes a replica that the gate did not admit. Then a commit can land in a store that no reader of that case uses.
Extends: BT-05-006
Refines: BT-05-005
BT-05-009 MUST For a tree gated on a role held in the case, the role holder, the receiving actor and the store owner MUST be one actor.

These three identities are specified separately. If any two differ, the gate checks an actor that holds no role, skips with SUCCESS, and writes nothing. No error shows the skip, so a later node can separate the three again and nobody sees it.
Refines: BT-05-006

Workflow-Specific Trees

ID Priority Requirement Related
BT-06-001 MUST All protocol-significant behavior MUST be implemented as BT nodes or subtrees. There is no "simple enough to skip" threshold.

The BT is the domain documentation; behaviors outside the tree are invisible to analysis, audit, and explainability.
BT-06-002 MUST Prototype use-case BTs MUST correspond to identifiable subtrees of the canonical CVD protocol BT

When a use-case tree agrees with the canonical protocol tree, a reviewer can check it against the protocol design. A tree with no known equivalent can become different from the protocol, and nothing shows the difference (BTC-01-001).
BT-06-003 SHOULD BT nodes SHOULD be deterministic

A deterministic node gives the same result for the same store and input. Thus a test can repeat a run, and you can find the cause of a failure. Randomness belongs in the simulation backends (BT-23-001), not in protocol nodes.
BT-06-004 MUST Individual BT nodes MUST be simple and focused on a single concern (e.g., a single exception check or a single boolean condition)

Surfacing logic in the tree makes the process auditable without reading implementation code; if it is not in the tree it cannot be reasoned about from the tree alone.

DataLayer Integration

ID Priority Requirement Related
BT-07-001 MUST BT nodes MUST interact with DataLayer via Protocol interface

Nodes that depend on the DataLayer Protocol, not on one specific store, operate with any adapter. This includes per-actor stores and test doubles. It also keeps adapter imports out of the core.
BT-07-002 MUST BT nodes MUST use type-safe DataLayer operations

Typed reads and writes find an object of the incorrect type at the point where a node reads it. They do not let a later node trust that value. With an untyped read, a node can act on the incorrect kind of object and fail far from the cause.
BT-07-003 MUST State transitions MUST be logged at the level specified by SL-04-001

An operator follows state transitions to understand a case. When each transition goes to the log at the agreed level, the operator can find it in the log of every component. It also stays separate from debug messages.
Refines: SL-04-001

Command-Line Execution

ID Priority Requirement Related
BT-08-001 MAY System MAY provide CLI interface for BT execution

When a developer can run a tree from the command line, the developer can test it without a server, an inbox or a peer.
BT-08-002 SHOULD CLI SHOULD support invoking specific trees with test data

When you run one tree with selected data, the inbox and dispatch path do not have an effect on it. Thus you can find and repeat a defect in the tree more easily.
BT-08-003 SHOULD CLI SHOULD log BT execution visualization

A diagram of the tree as it ran shows which branch the tree took and where it failed. A result of pass or fail alone does not show this.

Actor Isolation

ID Priority Requirement Related
BT-09-001 MUST Each actor MUST have isolated BT execution context

Each actor makes its own decisions from its own state. If two actors use one run context, the run of one actor can read or change the state of the other actor. Then the case records of the two actors are not independent.
BT-09-002 MUST NOT Actor blackboards MUST NOT share state

Blackboard storage is process-global, and many actors can run in one process. With a shared key, the run of one actor can read a value that the run of a different actor wrote (BT-17-007).

CASE_MANAGER Role Management

ID Priority Requirement Related
BT-10-001 MUST Report validation MUST trigger VulnerabilityCase creation

When a report is valid, the receiving actor starts to coordinate the vulnerability. Every later CVD activity is part of a case. Without the case, the activities that follow have no context.
Implements: VP-02-015
BT-10-006 MUST This codebase's CASE_MANAGER gates (BT-10-004) MUST test for the CVDRole.CASE_MANAGER role on the actor's participant record, not for a CaseActor object or a per-case actor identity.

CheckIsCaseManagerNode reads the role from the participant record and needs no notion of a CaseActor entity, so the gate works for any actor the Case Owner delegates the role to.
Implements: BT-10-004

VFD/PXA State Machine Usage

ID Priority Requirement Related
BT-12-001 MUST New code that implements VFD or PXA state transitions MUST use create_vfd_machine() and create_pxa_machine() in vultron/core/states/cs/machine.py as the authoritative source of valid transition sequences.

Ensures the transitions machines remain the normative definition of valid VFD/PXA state progressions as new features are added, preventing divergence between the machines and the implementation.
BT-12-003 MUST NOT New code MUST NOT add hand-rolled transition logic for the VFD or PXA state dimensions.

Hand-rolled transition logic is a second definition of the valid VFD and PXA moves. It can allow a move that the machines refuse, and no test of the machines finds it.
Extends: BT-12-001
BT-12-002 SHOULD A high-level BT node that writes a target VFD state SHOULD advance through each required intermediate state when the actor starts below the entry point.

A vendor that reports a fix as ready has known about the vulnerability since it engaged. But the VFD machine gets to fix-ready (VFd) only through vendor-aware (Vfd). If each caller must go through Vfd first, each call site must know the order of the machine. Thus, when the actor is still at vfd, the node does the implied V step itself. The node then records two ParticipantStatus entries and logs two CS transitions, one for each step.
BT-12-004 MUST NOT A high-level BT node that writes a target VFD state MUST NOT require its caller to advance the actor through the intermediate states first.

If each caller must advance through Vfd first, each call site must know the order of the VFD machine. A node that takes the implied step itself keeps that order in one place.
Extends: BT-12-002

Concurrency

ID Priority Requirement Related
BT-11-001 MUST Prototype MUST process messages sequentially (FIFO order)

Eliminates race conditions in prototype phase
BT-11-002 MUST NOT Sequential processing MUST NOT block HTTP response (BackgroundTasks)

A sending peer waits for the HTTP response. If the inbox processes a payload inside the request, every sender waits for the tree runs of the receiver, and requests time out under load. Thus the inbox answers first and then processes the payload in the background.
BT-11-003 MAY Future optimizations MAY introduce resource-level locking

When the inbox processes one message at a time, the design is simple, but throughput is low. A lock for each resource, for example each case, lets unrelated messages run at the same time. Messages that touch the same state still run one after the other.
BT-11-004 MUST BTBridge MUST acquire a threading.RLock (re-entrant lock), not a plain threading.Lock, when serializing BT execution. Any code path in which execute_with_setup() calls back into BTBridge (directly or transitively) will deadlock with a plain Lock because the same thread attempts to acquire a non-reentrant lock it already holds.

BTBridge.execute_with_setup() invokes user-supplied setup and teardown hooks. In integration and demo scenarios these hooks may trigger secondary BT executions via the same bridge instance. A plain Lock would deadlock on the second acquisition from the same thread. An RLock allows re-entry by the owning thread while still blocking other threads.
Implements: BT-11-001

BT Failure Diagnosis

ID Priority Requirement Related
BT-13-001 MUST After any BT execution that returns FAILURE, code MUST retrieve the failure reason via BTBridge.get_failure_reason(tree).

py_trees sets feedback_message on the failing child node, not on the parent Sequence. get_failure_reason() walks the chain of failed nodes to the failing leaf, taking the last failed child of each composite, and returns its message.
BT-13-003 MUST NOT Code MUST NOT log or inspect result.feedback_message or bt.root.feedback_message to diagnose a failure. The one exception is a node that raised, where result.feedback_message carries the bridge's composed exception message.

A py_trees Sequence root's feedback_message is always "" when a child fails, whatever the failing child set. A log of it reads the same as no error, so the failure is silent. A node that raised set no status, so get_failure_reason finds no failing leaf, and the composed message is the only reason there is.
Extends: BT-13-001
BT-13-002 MUST Every BT execution site MUST apply the BTBridge.get_failure_reason() pattern, not only one BT class or protocol flow.

If one execution site reports a failure reason and a different site loses it, some failures stay silent. One helper at every site puts the message of the failing node in every log (BT-13-001).
Refines: BT-13-001 — Scope is all BT execution sites, not just sync
BT-13-004 MUST Each place in the codebase that logs a BT result MUST use BTBridge.get_failure_reason().

A log line is where an operator reads why a tree failed. A log of the root message shows an empty reason, so every site that logs a result needs the helper (BT-13-001).
Extends: BT-13-002

Peer Broadcast Failure Semantics

ID Priority Requirement Related
BT-14-001 MUST Any BT node or subtree that performs protocol-visible peer broadcast fan-out MUST return FAILURE when broadcast preparation or outbox enqueueing fails. A guaranteed SUCCESS fallback that masks delivery failure MUST_NOT be used.

Silent success on failed fan-out causes undetected peer state divergence and hides correctness faults from parent tree control flow.
BT-14-002 SHOULD Peer broadcast fan-out paths SHOULD reuse a shared helper/subtree for recipient filtering, activity construction, and outbox enqueueing so the failure contract is consistent across workflow domains.

Duplicated fan-out implementations drift over time and re-introduce silent-failure behavior in only some pathways.
BT-14-003 MUST When a fan-out's catch-up backfill of a let-back-in, paused peer is held back at an older entry (SYNC-03-009), the fan-out MUST skip only that peer, keeping its pause, and return SUCCESS. Every other hold-back, including the join backfill's and the admission backfill node's, is a failure under BT-14-001.

The skipped peer keeps its pause, so the same hold-back recurs on every later commit in the case. Failing the fan-out would refuse each of those acts whole (CLP-07-015), so one broken old entry would stop the case from committing anything. The peer could hold the new entry only as a forward gap (SYNC-14-001), so skipping it loses nothing. The join and admission backfills keep failing, as decided on #5120: while a broken old entry exists, every later Accept of an Invite to the case is refused whole, so no one new can join until the entry is repaired.
Supersedes: BT-14-001
Uses definition from: SYNC-03-009

Trigger-Side Use-Case Contract

ID Priority Requirement Related
BT-15-001 MUST Trigger-side execute() methods MUST delegate state-machine transitions (RM, EM, CS) to BT leaf nodes via BTBridge, following the same pattern as received-side use cases.

State machine transitions are protocol-significant behavior (BT-06-001). A transition inside execute() is not subject to the audit, logs and failure reports of the tree through get_failure_reason(). When both sides use one pattern, a reader finds every transition in a tree, on whichever side it started.
Refines: BT-06-001 — SM transitions are protocol-significant behavior with no skip threshold
Refines: BT-06-006 — SM transitions performed outside a BT violate BT-06-006
BT-15-002 MUST NOT Trigger-side execute() methods MUST NOT call domain lifecycle methods (e.g., EmbargoLifecycle, direct ParticipantStatus writes of rm/em state) outside a BT execution context.

Direct lifecycle calls in execute() make protocol transitions invisible to BT-level audit and observability tooling. The BTBridge pattern (instantiate BT → execute_with_setup() → introspect result) is the required contract for all use-case execute() methods that perform state transitions.
Refines: BT-06-006
BT-15-003 MUST A BT-backed trigger whose request names a case MUST run the case-wide clock decisions (the embargo end-time check, EMB-13-003) as the leading, CASE_MANAGER-gated step of its own one tree, the same clock-decision stage a received tree runs (CLP-10-025), and never as a separate tree run before it. The terminate-embargo trigger is the one exception: its own tree takes the end-time path once the end time has passed and answers for it. An embargo trigger also takes the overdue-invitation sweep (CM-28-015) in that stage, after the case-wide decisions; terminate-embargo takes the sweep alone. A trigger that runs no tree changes no case state and takes no clock decision.

An overdue embargo is a fact about the case, at every entry point. Without the check, a trigger can extend an embargo whose end time has passed, for example when it accepts a pending revision. The check runs as the first stage of the trigger tree. Thus each request has one tree, and the check and the trigger effects have one run and one outcome (ADR-0214).
Extends: BT-15-001
Uses definition from: CLP-10-025
Uses definition from: EMB-13-003
Uses definition from: CM-28-015

Role-Gated BT Subtrees and Blackboard Hygiene

ID Priority Requirement Related
BT-17-001 MUST Any BT subtree whose semantics are restricted to the CVDRole.CASE_MANAGER actor MUST be wrapped in a role-guard composite using CheckIsCaseManagerNode at tree-composition time, not enforced via application-layer guards outside the tree.

Received-side trees run as the receiving actor. Without a role guard in the tree, a CASE_MANAGER-only node runs at every actor that receives the activity. This includes participants that must only record it. If such a run also sets a once-only marker, it can take the slot and stop the run of the CASE_MANAGER (BT-17-002). A guard in the tree shows in the tree structure, and it applies on every path that runs the subtree. The canonical role-guard composite is a Selector. It has a guarded Sequence (CheckIsCaseManagerNode and the action node) and a Success("Skipped") fallback.
Refines: BT-06-001 — CASE_MANAGER-only behavior is protocol-significant; it must live inside the tree with an explicit guard
BT-17-002 MUST A module-level idempotency set (a set[str] used to track "already fired" state for a BT node) MUST be paired with a role guard (BT-17-001) that prevents any actor other than the intended role from writing to the set.

Module-level sets are per-process, not per-container. In a Docker deployment, each actor process has its own set; a phantom fire in process A does not affect process B. However, within a single process, two phantom fires (the wrong actor fires before the correct one) can race: the phantom claims the set slot first and silently blocks the legitimate fire. Pairing the set with a role guard ensures only the correct actor can claim the slot.
Uses definition from: BT-17-001
BT-17-003 MUST A BT node that takes a no-op path MUST write None to each output blackboard key it normally sets before it returns. Examples of a no-op path are an empty recipient list and a guard condition that is not met.

py_trees.blackboard.Blackboard.storage is process-global. On exit, execute_with_setup resets only the keys on its managed_keys allowlist. Thus a key that a node writes stays after the run, unless the allowlist includes it. A consumer that reads such a key can get the value from an earlier run, when the producer stops early and does not write None. Then independent runs share data, and no error shows it.
BT-17-004 MUST A consumer BT node that reads an output key set by a peer producer node MUST treat both KeyError (key never written) and a None value (producer took no-op path per BT-17-003) as equivalent no-op sentinels and skip any write-dependent action.

A node that only handles KeyError but not None will incorrectly proceed with a None value on the second run after the producer has cleared the key to None. Both states mean "producer had nothing to produce this cycle."
Uses definition from: BT-17-003
BT-17-005 MUST Tests for a received-side use case that exercises a BT guarded-commit path MUST pass receiving_actor_id equal to the actor holding CVDRole.CASE_MANAGER in actor_participant_index, not the CaseActor service entity ID.

CheckIsCaseManagerNode compares actor_id with the participant that holds CVDRole.CASE_MANAGER in actor_participant_index. It does not compare it with the id of the CaseActor service resource. A test that uses the service id fails the role check, and no error shows. The guarded commit does not run, the RM state takes the deferred path, and the test can pass for the incorrect reason.
Derives from: BT-17-001 — The role guard identity check is what makes this fixture requirement necessary
BT-17-006 MUST A received-side use case that executes a BT containing GuardedCommitCaseLedgerEntryBT MUST call execute_with_setup with the receiving actor, never with request.actor_id (the sender).

request.actor_id is the sender of the inbound activity. The receiving actor is the CASE_MANAGER that owns the ledger, and CheckIsCaseManagerNode checks its role. A tree that runs as the sender fails that check, so the guarded commit skips the ledger entry with no error. With per-actor storage, actor_id also selects the store, so a run as the sender reads and writes the wrong replica.
BT-17-009 MUST When request.receiving_actor_id is absent, a received-side use case that executes GuardedCommitCaseLedgerEntryBT MUST take the owner of its store as the receiving actor.

The system always calls a received-side use case with the store of the receiving actor. Thus the owner of that store is the one safe fallback, and the sender never is.
Extends: BT-17-006
BT-17-010 MUST A received-side use case that executes GuardedCommitCaseLedgerEntryBT MUST fail when neither request.receiving_actor_id nor its store yields an identity.

With no receiving identity, the tree cannot select a store or pass the CASE_MANAGER check. A run without one acts as an identity that is not the receiver, so the use case fails instead.
Extends: BT-17-006
BT-17-011 MUST A node that targets the sender's participant MUST keep the sender's ID in a private attribute that DataLayerAction.setup() does not overwrite. This applies to each node in a received-side tree that contains GuardedCommitCaseLedgerEntryBT.

The setup writes the receiving actor's ID over the actor of the node. A write about the sender, for example to advance its RM state, still needs the sender's ID, so that ID must be where the setup does not write.
Extends: BT-17-006
BT-17-007 MUST BTBridge.execute_with_setup MUST restore every blackboard key that it or setup_tree writes to that key's pre-execution state before it returns, on every outcome.

Blackboard.storage is process-global. Thus a nested execute_with_setup that uses the same key overwrites the value of the outer run. Unless each key goes back to its earlier value, the outer run continues with the values of the inner run.
BT-17-012 MUST The keys that BTBridge.execute_with_setup restores MUST include the injected ports, actor_id, activity and each **context_data key.

These are the keys the bridge writes on every run. Nodes read /actor_id again in initialise(), so a nested run as a different actor that is not undone gives its identity to later siblings and to payloadSnapshot.actor (CLP-07-003).
Refines: BT-17-007
BT-17-013 MUST The set of keys that BTBridge.execute_with_setup restores MUST be extensible to a key that a node writes mid-tree.

No single node can clear such a key on every outcome, because a memory=False Sequence can stop before the owning node ticks. Only the bridge runs on every outcome.
Extends: BT-17-007
BT-17-014 MUST NOT A caller MUST NOT use a key that BTBridge.execute_with_setup restores as an output channel. A node returns a value to its caller through a mutable object that the caller holds, such as a result_out dict.

A restored key goes back to its earlier value when the call returns, so a result written there is lost.
Extends: BT-17-007
BT-17-008 MUST Every emit node in a received-side tree's effect section MUST sit behind a guard. The guard is the CASE_MANAGER gate (BT-17-001) or a check that the executing actor is the actor the emit speaks for.

An emit outside a guard runs at every receiver of the activity. The guard makes sure that only the actor the emit speaks for sends it. There are two arms and no third: a recorded exemption waives this requirement rather than meeting it, so an emit that can carry either arm carries it instead of an exemption. Neither arm is something a tree asks for by hand. The receive-tree factory places the CASE_MANAGER gate round the effects a tree declares as the CASE_MANAGER's, and the path a message type declares (HP-01-038) is the same statement where the declaration names that path alone. The second arm is a leaf that admits the executing actor alone, marked so the factory's walk can see it: the walk reads composites, and any leaf could otherwise be the check.
Uses definition from: BT-17-001 — BT-17-001 requires the gate for CASE_MANAGER-only subtrees; this entry says every received-side emit is gated by role or by sender
Depends on: HP-01-038 — a manager-only path declaration is the CASE_MANAGER gate made as a declaration, so it bounds the emits of the tree it declares
BT-17-015 MUST NOT A received-side tree MUST NOT emit, as the executing actor's own act, an activity that another actor authored.

If an actor sends the act of a different actor again under its own name, it claims an act that it did not author. An on-behalf send names the doer in actor, the requester in attributedTo and the request in inReplyTo (CM-24-001, CM-24-002, CM-24-020).
Extends: BT-17-008
BT-17-016 MUST NOT A received-side tree MUST NOT emit an activity whose only recipient is the executing actor.

An actor does not send its own emission to itself (ADR-0109), so a self-addressed emit is a loop.
Extends: BT-17-008
BT-17-017 MUST create_receive_activity_tree MUST be the only place where a received-side tree acquires the CASE_MANAGER gate.

When only the factory adds the gate, every received tree gets the same gate, in the same position.
Extends: BT-17-008
BT-17-018 MUST create_receive_activity_tree MUST take gated effects as manager_effects, ungated ones as replica_effects, and refusal effects as refusal_effects, gated on the CASE_MANAGER (CLP-10-022).

When each kind of effect has its own parameter, the factory can place it and gate it. No caller has to build the gate itself.
Implements: BT-17-008
Uses definition from: CLP-10-022
BT-17-019 MUST create_receive_activity_tree MUST refuse an emit-capable node in replica_effects unless the tree declares a named exemption that carries a reason.

An emit in replica_effects runs at every receiver. The exemption check makes each ungated emit a stated choice, not an accident.
Extends: BT-17-008

Simulation Fuzzer Node Layout

ID Priority Requirement Related
BT-16-001 MUST Probabilistic simulation (fuzzer) BT nodes MUST reside in vultron/demo/fuzzer/.

Demo/simulation nodes are external-dependency touchpoints, not production protocol behaviors. Keeping them in vultron/demo/fuzzer/ makes the simulation/production boundary explicit and prevents simulation artifacts from leaking into core protocol logic.
BT-16-006 MUST NOT Probabilistic simulation (fuzzer) BT nodes MUST NOT be placed in vultron/core/behaviors/ or vultron/bt/.

A fuzzer node in vultron/core/behaviors/ puts simulation behavior into core protocol logic. A fuzzer node in vultron/bt/ changes the frozen legacy simulator (BT-02-002). Either breaks the boundary between simulation and production.
Derives from: BT-16-001
BT-16-002 MUST The probabilistic base types (WeightedBehavior subclasses) for simulation nodes MUST be defined in vultron/demo/fuzzer/base.py using the py_trees.behaviour.Behaviour base class.

All py_trees-based BT execution uses the standard py_trees library (ADR-0008). Centralizing probabilistic base types in one module provides a single implementation point for all weighted-probability simulation nodes and avoids duplication across domain modules.
BT-16-003 MUST Each simulation fuzzer node MUST be named after the external-dependency touchpoint it represents, for example EvaluateEmbargoProposal or DeployFix.

Fuzzer nodes are named integration points where production logic will eventually replace the probabilistic stub. Explicit naming and documentation preserves the connection between simulation behavior and future implementation targets.
BT-16-007 MUST Each simulation fuzzer node MUST have a docstring naming its semantic function in the CVD process, its external input category and its approximate success probability. The categories are system integration, human decision and environmental check.

The person who replaces a stub with production logic needs to know what that logic must do, what kind of input it takes, and how often the stub succeeds. Without the docstring, the fuzzer node is the only record of the touchpoint, and that knowledge is lost.
Extends: BT-16-003
BT-16-004 MUST Simulation fuzzer modules MUST be organized by CVD domain: vultron/demo/fuzzer/base.py (probabilistic infrastructure), vultron/demo/fuzzer/embargo/ (embargo management), vultron/demo/fuzzer/messaging.py (inbound message handling), and vultron/demo/fuzzer/report_management/ (report lifecycle sub-workflows as parallel submodules).

Domain-aligned module organization mirrors the workflow structure of the existing vultron/bt/ simulation and makes cross-references between simulation stubs and production use cases straightforward for future implementers.
BT-16-005 SHOULD Each simulation fuzzer node SHOULD be categorized in its docstring by automation potential: High (fully automatable via API or policy rule), Medium (partially automatable with human oversight required), Low (inherently human-driven; automation limited to notifications or task triggers), or TerminalPlaceholder (terminal placeholder node with no real decision logic — an AlwaysSucceed or AlwaysFail fallback leaf with no external dependency).

Automation potential tells a future implementer which type of integration a stub needs: an API or policy rule, a step that a person supervises, or only a notification or task. TerminalPlaceholder identifies a leaf with no decision logic. Thus nobody reads it as "not applicable" or as a node with high automation potential.

Call-Out Point Abstraction Layer

ID Priority Requirement Related
BT-18-001 MUST Every capability declaration MUST describe its call-out point's blackboard contract in its class docstring. The contract is the set of input keys it reads before dispatch, the set of output keys, with types, written when it answers yes, and the set of refusal keys written when it answers no.

The blackboard contract is the integration seam between the tree and the backend. Without an explicit contract, swapping from a fuzzer backend to a real implementation is a guess — the real backend may omit writing a key that a downstream node expects, causing silent failures. The docstring earns its place alongside the typed-port declaration because a reader deciding whether a capability fits their system should not have to reconstruct intent from port metadata; the declaration is what a test enforces, and the prose is what makes the seam legible. A backend answers yes, no or error (ADR-0183), and only yes and no write the blackboard, so the contract names the keys of those two.
BT-18-016 MUST The class docstring of a capability declaration MUST agree with its typed-port declaration (BT-18-012), which is the authoritative, machine-readable contract.

The docstring is for a human reader, and the typed-port declaration is what a test enforces. If the two disagree, a reader trusts a contract that the code does not keep.
Extends: BT-18-001
Uses definition from: BT-18-012
BT-18-002 MUST A call-out point backend, fuzzer or real, MUST give a value for every declared output key when it answers yes.

Downstream BT nodes rely on declared output keys being present after a call-out point succeeds. A fuzzer that answers yes without synthetic output for those keys produces a contract violation: a downstream node reads a missing key and fails, but the failure is attributed to the downstream node rather than the backend. Both fuzzer and real backends must be contract-conformant to make backend swaps transparent. The seam refuses a yes that omits one (BT-18-036).
Uses definition from: BT-18-012 — BT-18-002's "declared output keys" are the output ports that BT-18-012 makes the authoritative declaration, which is what makes the requirement checkable rather than reviewable.
BT-18-003 MUST The fuzzer backend for a data-producing call-out point (Evaluator, Retriever, or Composer shape) MUST give synthetic, type-conformant data for the declared output keys when it answers yes. The data does not need to be semantically meaningful.

If the fuzzer backend omits output writes that a real backend would perform, the demo/simulation layer cannot serve as a faithful stand-in during development. Maintaining the same output contract ensures that demo scenarios exercise the same downstream code paths as production runs.
BT-18-004 MUST A call-out point node MUST be constructed via a backend factory callable.

Factory-based injection is the established BT construction pattern in this codebase. Requiring the factory as a parameter (rather than hardcoding the fuzzer import) is what makes each call-out point an actual injection seam rather than a tightly-coupled stub. Without this, replacing any backend requires editing the tree-building function, defeating the abstraction layer's purpose.
BT-18-008 MUST Tree-building functions that contain call-out points MUST accept the backend factory as a parameter (or as an entry in a factory mapping).

Accepting the factory as a parameter makes each call-out point an actual injection seam rather than a tightly-coupled stub; replacing a backend then requires no changes to the tree-building function.
BT-18-009 MUST The fuzzer factory MUST be the default value for the backend factory parameter of tree-building functions.

A fuzzer default ensures demo scenarios work without explicit backend configuration until a real implementation is available, while still allowing injection of alternative backends at call sites that opt in.
BT-18-005 MUST The ADR-0024 seam-structure decision tree alone MUST determine the call-out point shape of a fuzzer node. That tree asks how external input enters the call-out point and how output exits it.

Automation potential and call-out shape describe different things. Automation potential tells if the logic can run without a person. Shape tells what goes into and out of the call-out point, and in which direction. A Retriever that uses a REST API is still a Retriever. The automation only means that its implementation needs no human action. If you select the shape from the automation potential, you build the incorrect call-out point, and you must then do the work on it again. BT-18-013 lists the canonical shapes, and BT-18-028 defines each one by what it produces.
BT-18-017 MUST NOT Automation potential MUST NOT be a criterion for assigning a fuzzer node the ProtocolInternal shape. A node whose inputs come from an external source, or whose outputs affect an external system, is a Retriever, Evaluator, Composer or Actuator.

A node with a High automation potential can still take input from outside or affect an external system. Its automation only means that its implementation needs no human action. If automation potential sets the shape, the node is built as ProtocolInternal, and its seam is lost.
Derives from: BT-18-005
BT-18-006 MUST A node that queries an external system synchronously and answers only yes or no, with no output, MUST be classified as a Retriever, not a Sentinel — and per BT-18-013 Sentinel is not a call-out capability shape at all, so Retriever is the only available classification. The defining criterion for Retriever shape is the synchronous on-demand query pattern, not the richness of the returned data; a boolean is the simplest possible structured fact a Retriever may return. A Sentinel, by contrast, monitors a condition continuously or is triggered by an external event and calls a trigger endpoint when the condition becomes true — the flow direction is Sentinel → trigger endpoint → protocol, not protocol → query → external system.

Nodes such as MitigationDeployed, MitigationAvailable and HaveExploit return only SUCCESS or FAILURE, so they look like Sentinels. But the tree calls them when it needs them, and they ask an external system for the current status. That is the Retriever pattern. The tree does not call a true Sentinel. A Sentinel runs by itself and calls a trigger endpoint when a condition is true. This criterion prevents the classification of on-demand binary queries as Sentinels.
Refines: BT-18-005 — BT-18-005 establishes that shape is determined by the seam-structure decision tree; BT-18-006 resolves the specific Sentinel vs. Retriever ambiguity for binary-result external queries.
Uses definition from: BT-18-013 — BT-18-013 is why Retriever is the only available answer, since Sentinel is not a call-out shape.
BT-18-010 MUST A binary-result Retriever MUST declare an empty output-port set; the structured fact is the verdict, yes or no, which the seam turns into SUCCESS or FAILURE, not a blackboard write. As with every capability contract, the authoritative declaration is the typed-port declaration required by BT-18-012 and the node docstring describes it (BT-18-001).

BT-18-001 through BT-18-003 require every call-out point to declare its complete blackboard contract. A binary-result Retriever has an empty output-key set; that empty set MUST still be explicitly declared so that the absence of output keys is documented as intentional rather than an oversight, and backend swaps remain transparent. An empty declaration is also what makes the BT-23-013 check decidable, because a capability that declares no output ports is not data-producing, so a bare constant-status default is a conforming default for it.
Refines: BT-18-012 — BT-18-012 makes the typed-port declaration the authority for every capability contract; BT-18-010 states what that declaration contains for a binary-result Retriever — the empty set, declared rather than omitted.

See also: BT-18-001 — context for the reader
BT-18-007 MUST An Evaluator call-out point that decides to block downstream BT execution MUST answer no, with the reason for the decision. Reasons include an editorial rejection, a legal hold, a compliance failure, or any other non-approval decision. The seam then fails the node.

A Sequence stops and returns FAILURE when a child returns FAILURE. That is how py_trees blocks a path. A field value such as approved=False does not stop a Sequence, because no node reads it as a gate. Thus, if a rejection uses such a field, the next step runs. A boolean approval flag on the output record of an Evaluator is thus a sign of a bad design. The exception is a flag that is the only input to a later ProtocolInternal gate node.
BT-18-038 MUST An Evaluator call-out point that cannot decide, for example because a service it needs is unreachable or rejects its credential, MUST answer error, not no.

A no is recorded as a decision about the request, and a received tree may keep it as a permanent decline (ADR-0183). An outage answered as no would decline a request that nobody judged. An error leaves the message unjudged and held, so the re-run asks again (BT-18-034).
Extends: BT-18-007
BT-18-011 MUST A call-out point backend MUST answer synchronously: within one tick it answers yes, no or error, and it never returns Status.RUNNING.

The execution model of Vultron cannot pause a tree. If the root returns RUNNING, the bridge ticks it again until max_iterations, and then fails without the name of the node. A node asks and stops, and it does not pause. This is the general case of the codebase-wide invariant that no Vultron BT node returns RUNNING (ADR-0080). The three verdicts are the whole answer (ADR-0183), so "not yet" is never one of them.
BT-18-018 MUST A runtime guard at the call-out seam MUST reject a Status.RUNNING return by raising an error that is not a VultronError.

A call-out backend comes from outside the repository, so a static scan cannot see it. Only a runtime guard at the call-out point can. The error is not a VultronError, so the bridge reports bad backend wiring as an internal error, not as a protocol outcome.
Extends: BT-18-011
BT-18-019 MUST A static architecture check MUST fail when any node under vultron/ returns Status.RUNNING.

A node in the repository that returns RUNNING makes the bridge tick until max_iterations and fail without the name of the node. A static check finds that node before it runs.
Verifies: BT-18-011
BT-18-012 MUST A named capability MUST declare its blackboard contract as py_trees typed ports (ADR-0044 INPUT_PORTS / OUTPUT_PORTS). The typed-port declaration is the authoritative contract, and the class docstring required by BT-18-001 describes it.

BT-18-002 is enforceable only if the layer that must obey the contract can read it as data. Nobody can check a contract that is only docstring text. ADR-0044 already requires typed ports for every node in vultron/core/behaviors/. Typed ports check types at runtime on read and on write. Thus, with typed ports, the capability contract is enforceable without a second registry.
Extends: BT-18-001 — BT-18-001 governs the human-readable description of the contract; BT-18-012 governs the authoritative machine-readable declaration. The two describe one contract in two registers and must agree.
BT-18-020 MUST NOT A capability declaration MUST NOT live in vultron/demo/.

Core cannot read a contract in vultron/demo/ at all, because BTND-04-002 forbids the import. Without a contract that core can read, the DETERMINISTIC default cannot know which outputs to write (BT-23-013).
Extends: BT-18-012
BT-18-021 MUST Each capability MUST carry its ports on its own core-owned declaration, not on the shape base class that many capabilities share. Its probabilistic simulation node stays in vultron/demo/fuzzer/ (BT-16-001) and binds to that declaration rather than restating the contract.

A shape base class is shared by many capabilities, so it cannot carry the contract of one capability. When the declaration is separate from the simulation node, core owns what the capability promises, and demo owns one way to simulate it.
Extends: BT-18-012
See also: BT-16-001 — context for the reader
BT-18-013 MUST NOT There are exactly four call-out capability shapes: Evaluator, Retriever, Composer, and Actuator. Sentinel MUST NOT be classified as a call-out capability shape. A Sentinel is a call-in integration pattern: a process that monitors a condition and acts on its own initiative, not one the protocol consults. Thus a Sentinel has no call-out point node, no blackboard contract, no domain bundle field, and no backend factory.

The call-out machinery that a capability shape uses defines that shape. This machinery is a backend factory, a domain bundle field, a blackboard contract, the synchronous-answer guard (BT-18-011), and a ceiling or floor default (BT-23-002). None of this applies to a monitor, because the protocol never calls it. The flow goes from the monitor to a trigger endpoint and then to the protocol, which is the opposite direction of a call-out. Thus a monitor classified as a capability shape claims a contract that it cannot have. That causes the incorrect classification that BT-18-006 prevents. The name call-in pattern tells the flow direction that makes the monitor different. It also puts the monitor with the concerns of a process that acts independently: its own schedule, its own credentials, and possibly its own protocol identity. A definition by information source gives the incorrect classification for a participant monitor. That monitor reads the replicated state of the case, but the protocol never asks it for an answer.
BT-18-022 MAY A Sentinel MAY be a case participant that observes case state through ledger replication and acts by emitting protocol messages.

The party that initiates classifies a Sentinel, not the source of the information it monitors. A participant monitor reads the replicated state of the case, but the protocol never asks it for an answer. A definition by information source would give it the incorrect classification.
Uses definition from: BT-18-013
BT-18-014 MUST NOT A question requiring a decision from another actor in the case MUST NOT be modelled as a call-out point. It is a protocol ask: the actor emits the request, terminates successfully, and acts on the reply when it arrives (ADR-0080).

A call-out point gives its answer in the same tick that asks. Thus you can use it only where an answer already exists. A decision that belongs to a different actor does not exist when the tree asks for it. Thus a gate that is a call-out point can only answer no. The Case Owner approval gates show this problem (ADR-0080). The two mechanisms are not interchangeable. The party that holds the answer sets the choice. Thus the rule is a MUST, not a recommendation.
Constrains: BT-18-005 — BT-18-005 assigns shape by seam structure once a seam is known to be a call-out point; BT-18-014 decides whether it is one at all.
BT-18-023 MUST A question that a service the actor itself operates can answer within a single BT tick MUST be modelled as a call-out point.

A call-out point gives its answer in the same tick that asks. Where the actor's own service already has the answer, a call-out point gets it without a round trip to another actor.
Extends: BT-18-014
BT-18-024 MUST An action with no representable not-yet state MUST be refused rather than asked about.

A protocol ask waits for a reply, so the actor must record that the action is not done yet. If the model has no state for that, the ask leaves nothing to resume from, and a refusal is the only correct answer.
Extends: BT-18-014
BT-18-015 MUST A call-out point backend MUST answer within a bounded time budget.

A backend runs on the ticking thread under FastAPI BackgroundTasks. A slow answer holds a worker, and the bridge ticks until it gets to max_iterations and then fails without the name of the node. That is the same unclear failure that BT-18-011 refuses, but it comes from slowness, not from a pause. Thus a synchronous answer is necessary, but it is not sufficient. The answer must also be fast.
Extends: BT-18-011 — BT-18-011 forbids suspending; BT-18-015 closes the remaining way a call-out can stall a worker — answering synchronously but too slowly.
BT-18-025 MUST NOT A call-out point backend MUST NOT perform unbounded blocking I/O in update().

Unbounded blocking I/O in update() stops a worker on the ticking thread, and no diagnostic shows. No budget can be met by a backend that waits without limit.
Extends: BT-18-015
BT-18-026 MUST The call-out time budget MUST be configurable per actor, not fixed by this specification or hard-coded in an implementation.

The duration is not part of the protocol, because it is local to one actor and no peer can see it. Thus two deployments with different values do not become different in their protocol behavior. An ask deadline is different in one important way. It goes on the wire in the AS2 endTime field, so both parties read the same number (ASK-03-004). Both durations are actor configuration (compare ASK-03-005). Wire visibility, not configuration, makes them different.
Extends: BT-18-015
BT-18-027 MUST A backend that exceeds the call-out time budget MUST surface as an internal error naming the offending node, not as a protocol FAILURE.

An overrun is a fault in the backend, not an answer to the question. An internal error that names the node shows the operator where the time went, and a protocol FAILURE would hide it as a decision.
Extends: BT-18-015
BT-18-028 MUST A call-out point node MUST be classified by what it produces. An Evaluator records a decision, a Retriever returns external data, and a Composer produces a content artifact. An Actuator causes a side effect in an external system and places no artifact on the blackboard.

This is how the ADR-0024 seam-structure decision tree (BT-18-005) answers its question of how output exits the call-out point, one answer for each shape. The output of a node, not the work that it does, separates the shapes. A node that calls an external system looks like a Composer, because it sends something out. If no content artifact comes back to the blackboard, the effect is the output, and the node is an Actuator.
Uses definition from: BT-18-013 — BT-18-013 names the four shapes; this entry defines each by its output.
Refines: BT-18-005 — Restates the seam-structure tree's output question for each shape.
BT-18-040 MUST An Actuator call-out point MUST answer error, not no, when it cannot confirm its side effect or its credential is rejected.

A no is a decision not to act, and the tree acts on it as one. A side effect that may or may not have happened is no decision, and a rejected credential is a deployment fault (ADR-0183). An error leaves the act unjudged, so a received message stays in holding and its re-run asks again (BT-18-034).
Extends: BT-18-028 — BT-18-028 defines the Actuator by its side effect; this entry says which verdict a side effect it cannot confirm gets. BT-18-038 is the same rule for an Evaluator.
BT-18-041 MUST An Actuator call-out point MUST act on exactly one target per call.

One call gives one verdict (BT-18-031). A call that acted on several targets would need a verdict for each, and "some done, some not" has no verdict, so partial success would hide inside one answer (ADR-0183). The capability declaration of an Actuator says so: every call takes one target.
Refines: BT-18-028 — Places the Actuator that BT-18-028 defines by its output.
BT-18-042 MUST A tree that acts on several targets MUST make one Actuator call per target.

Each call then gives its own verdict, so the tree sees which targets were acted on, and what it does after a no stays its own logic (ADR-0183).
Refines: BT-18-041
BT-18-043 MUST Each Actuator call MUST carry an idempotency id that the tree derives from the act and the target.

An error leaves a received message in holding, and the re-run asks every call-out point again (BT-18-034). A call that gets the id of its first run lets the backend see that it already acted. The received activity identifies the act, as it does for a rebuilt send (OX-06-002). A trigger is never re-run from holding, so its act takes an id of its own.
Refines: BT-18-041
BT-18-044 MUST NOT An Actuator backend MUST NOT repeat a side effect for an idempotency id it has already acted on.

The tree gives a re-run the ids of its first run (BT-18-043), but only the backend knows what it did in the external system. A backend that acts again on a known id would repeat the side effect that the id exists to prevent. It answers yes instead, because the side effect happened.
Uses definition from: BT-18-043
BT-18-031 MUST A call-out backend MUST give one answer per call: a verdict of exactly one of yes, no or error, and the data its capability declares for that verdict.

A binary answer gives a refusal no channel for its reason and makes "I could not tell" look like "no" (ADR-0183). A fixed verdict with typed data keeps the tree branching on SUCCESS and FAILURE only, and a new kind of data extends a declaration, never the verdict vocabulary. The pattern is the one a use-case result already follows one layer up (ADR-0095, ADR-0110).
BT-18-035 MUST A capability declaration MUST name the output ports written on yes and the refusal ports written on no, a reason at minimum.

The seam checks an answer against the declaration, so the declaration must name the data of both verdicts that write the blackboard. A refusal always has a reason, so the reason port is never optional.
Refines: BT-18-031
BT-18-032 MUST The call-out seam MUST turn an answer into tree behaviour. On yes it writes the declared outputs and the node succeeds. On no it writes the refusal payload to the declared refusal ports and the node fails. On error it raises an error that names the node and is not a VultronError.

When each tree reads the answer itself, a tree that ignores error turns an outage back into a permanent decision (ADR-0183). The seam is the one place that already guards every call-out (BT-18-018), so it is the one place that interprets the answer. The diagnostics of an error go into the raised error and the logs, never onto the blackboard.
Extends: BT-18-018
Uses definition from: BT-18-031
BT-18-036 MUST The call-out seam MUST reject an answer with any verdict but yes, no or error, or with data that its declaration does not name.

A backend comes from outside the repository (BT-23-004). An answer that the seam does not check could carry a key that no reader expects, or omit one that a reader needs (BT-18-002), and the failure would appear at a later node.
Extends: BT-18-032
BT-18-033 MUST NOT A tree MUST NOT read a call-out answer.

Only the seam turns an answer into tree behaviour (BT-18-032). A tree that holds a bare backend would read its verdict without the error path, so an error would become a FAILURE that the tree records as a decision.
Refines: BT-18-032
BT-18-037 MUST A call-out backend ticked anywhere but directly under the seam MUST raise an error that is not a VultronError.

The raise is how BT-18-033 is kept at run time: a bare backend in a tree fails the run as an internal error, so its verdict never reaches the tree without the error path.
Refines: BT-18-033
BT-18-034 MUST An error answer inside a received tree MUST leave the message unjudged. The run writes no refusal and no ledger entry, and the message stays in holding for a re-run.

The message is not judged because the backend could not decide. The re-run from holding asks again, and its answer is the decision (ADR-0183, ADR-0214).
Refines: BT-18-032

Routing-Gated State Mutation in Lifecycle BT Sequences

ID Priority Requirement Related
BT-19-001 MUST A BT Sequence that changes state and then routes an outbound message MUST resolve each routing prerequisite in a read-only guard before that change.

Committing a state change before verifying that the resulting outbound message can be constructed and queued creates a divergence window: local state reflects the new value while peers still hold the prior value because the broadcast was never sent. Moving the routing guard before the mutation eliminates the most common divergence cause without requiring full transactional rollback. The outbox is the reliability boundary: once the message is written to the outbox, delivery and retry are the outbox's responsibility.
BT-19-004 MUST A Sequence whose routing prerequisite is absent MUST fail at its guard with no state change.

A Sequence that changes state and then cannot send leaves local state ahead of its peers, because the broadcast was never sent. A failure at the guard leaves both sides at the prior value.
Extends: BT-19-001
BT-19-003 MUST In protocol lifecycle BTs, the routing prerequisites of an EM, RM or CS state-transition sequence MUST include CASE_MANAGER actor ID resolution and outbox availability.

Protocol state divergence (e.g., local EM=EXITED while peers hold EM=ACTIVE) is the primary failure mode when routing prerequisites are absent. Residual mid-send failures after state mutation are recoverable via ledger-sync catch-up (SYNC-10); prerequisite-missing failures are not, because the broadcast was never attempted.
Refines: BT-19-001 — Specifies the CVD-protocol-specific routing prerequisites that BT-19-001 requires to be resolved in the guard node.
BT-19-005 MUST A missing CASE_MANAGER entry in actor_participant_index MUST make the sequence fail at the guard with zero DataLayer state change.

With no CASE_MANAGER to address, the transition cannot be broadcast. A mutation that runs anyway leaves local state ahead of its peers, for example local EM=EXITED while peers hold EM=ACTIVE. Ledger-sync catch-up cannot repair it, because no broadcast was attempted.
Extends: BT-19-003
BT-19-002 MUST Every path that triggers the same protocol lifecycle transition, for example embargo termination, MUST use one shared BT factory function.

Copies of one lifecycle operation gradually become different. One copy can check routing before it changes state, while a different copy changes state first. Then the defect that BT-19-001 prevents occurs again on one path. A single shared factory gives every call site the same semantics and the same guard order.
BT-19-006 MUST NOT A monolithic BT node that inlines both state mutation and activity dispatch in one update() method MUST NOT exist beside a canonical factory-composed equivalent.

A monolithic copy of a factory-composed operation can change state before it checks routing. Then the defect that BT-19-001 prevents occurs again on that one path.
Extends: BT-19-002

Production BT Collapse Patterns

Requirements for production BT subtrees that replace groups of simulator fuzzer nodes. Each collapse candidate reduces multiple granular simulator leaves to a smaller set of production call-out points with cleaner seam structure; individual requirements are provisional and subject to revision at implementation time.

ID Priority Requirement Related
BT-20-001 SHOULD The production create_acquire_exploit_strategy_tree factory SHOULD provide a HaveExploit Retriever and an EvaluateExploitStrategy Evaluator call-out point in place of the five simulator nodes. These are HaveExploit, ExploitPrioritySet, EvaluateExploitPriority, ExploitDeferred and ExploitDesired. The HaveExploit Retriever is kept as a separate seam for independent swapability (ADR-0027).

The five-node simulator sequence uses boolean flags to show one policy decision: if the actor gets an exploit. Production does not need these flags. Two call-out points, a Retriever and an Evaluator, replace the five simulator nodes. They also let you replace the exploit-repository query by itself. See ADR-0027 and docs/developer/reference/bt-fuzzer/rm-exploit.md.
BT-20-009 SHOULD The EvaluateExploitStrategy Evaluator SHOULD receive the case context and return an ExploitStrategyDecision record containing have_exploit, acquire, and rationale. The case context is the vulnerability state, the org policy, the threat landscape, and the HaveExploit query result.

One structured decision record replaces the boolean flags of the simulator. When the Evaluator receives the full case context, including the result of the Retriever, it makes the policy decision in one place.
Extends: BT-20-001
BT-20-002 SHOULD The production create_publication_tree factory SHOULD use the PrioritizePublicationIntents (Evaluator) output to gate its three per-artifact arms (exploit, fix, report) directly. It needs no separate NoPublish* bypass leaves and no PublicationIntentsSet flag check.

The NoPublish* bypass leaves and the PublicationIntentsSet flag check exist only because of how the simulator shows the tree. They are not call-out points. In production, the output of the PrioritizePublicationIntents Evaluator selects which arms run. The ShouldPublishX gate nodes have positive names per BTND-08-001. See ADR-0028 and docs/developer/reference/bt-fuzzer/rm-publication.md.
BT-20-010 SHOULD The PrioritizePublicationIntents Evaluator SHOULD return a structured PublicationIntentDecision record containing publish_exploit, publish_fix, publish_report, and rationale.

One field for each artifact lets each arm read its own intent. The rationale field records why the Evaluator decided as it did.
Extends: BT-20-002
BT-20-011 SHOULD Each publication arm SHOULD be a Selector(Sequence(ShouldPublishX, PrepareX, Publish), Inverter(ShouldPublishX)), so that an arm that is not intended is a graceful SUCCESS no-op.

An arm that is not intended must not fail the tree. The Inverter arm turns a negative intent into SUCCESS, so the other arms still run.
Extends: BT-20-002
BT-20-012 SHOULD Each publication arm SHOULD consist of a Composer that prepares the artifact, followed by a Publish pipeline (BT-20-004).

Preparing an artifact makes content, so it is a Composer. Publishing it is a separate pipeline with its own call-out points (ADR-0030).
Extends: BT-20-002
Uses definition from: BT-20-004
BT-20-003 SHOULD The production report-to-others workflow SHOULD be driven by an external call-in monitor (the Sentinel pattern, BT-18-013) that fires suggest-actor-to-case for each missing party it finds. A missing party is an actor who is not yet a participant but should be (party discovery).

The tree has no source for party discovery. An external monitor examines the case on a schedule or on an event, so the identification occurs where the information is. It is on the call-in surface (BT-18-013), so it connects through a trigger endpoint, not a bundle field. The suggest-actor-to-case protocol (Offer → CASE_MANAGER → CaseOwner → Invite → Accept → Record cascade) does the downstream work, so no inline tick-driven loop is needed at the outer level.
Uses definition from: BT-18-013
BT-20-013 SHOULD Where one is required, an inline report-to-others subtree SHOULD pair a candidate Retriever call-out with one suggest-actor-to-case Actuator per returned (actor_id, role) pair. The pair's role is that Actuator's explicit CVDRole parameter.

A single-pass, trigger-driven run can need the work inline. A Retriever for the candidates and an Actuator for each send keep the two external seams separate, and the explicit role tells the CASE_MANAGER what to offer.
BT-20-004 SHOULD The production create_publish_artifact_tree factory SHOULD replace the single Publish Actuator leaf with a pipeline of at least a Composer, then an Evaluator, then an Actuator. The Composer drafts the advisory artifact from case data, and the Evaluator reviews and approves the draft. The Actuator submits the finalized artifact to the external advisory platform.

The single Publish leaf of the simulator represents a full advisory publication workflow. In production, draft, review and submission are different operations, each with its own external call-out point. Submission causes an external effect but makes no artifact, so it is an Actuator (ADR-0024). Whether the review phase includes a broadcast-for-participant-comment step is an open design question for the implementation. See ADR-0030 and docs/developer/reference/bt-fuzzer/rm-publication.md.
BT-20-014 MAY The create_publish_artifact_tree pipeline MAY include an optional revision Composer between the Evaluator and the Actuator.

A reviewer can ask for changes to the draft. A revision Composer applies them before submission, so the Actuator submits the revised artifact.
Extends: BT-20-004
BT-20-005 SHOULD The production create_deploy_mitigation_tree factory SHOULD implement a DeployMitigationBT Fallback tree with four arms: a short-circuit arm for already-active mitigations, a deferred-RM arm, a deploy-if-available arm, and a monitor-if-desired arm.

Mitigation deployment is the fallback when no definitive fix is available. Each arm covers one condition of the deployer, so the tree gets to a defined outcome in each condition. MitigationDeployed and MitigationAvailable ask an external system for the current state. Thus they are call-out Retrievers, not DataLayerCondition nodes.
BT-20-006 MUST NOT The create_deploy_mitigation_tree tree MUST NOT include a CS state transition or protocol activity emission node; mitigation deployment is tracked externally (for example in a CMDB) and the protocol has no dedicated mitigation-deployed message type.

The VFD state machine tracks only vendor-aware/fix-ready/fix-deployed bits; there is no mitigation-deployed bit. Emitting a CS state transition or protocol activity from the mitigation tree would conflate fix-deployment semantics with mitigation tracking.
BT-20-007 SHOULD The shared monitoring/prioritization call-out seams (PrioritizeDeployment, MonitoringRequirement, MonitorDeployment) SHOULD be factored into a DeploymentMonitoringBundle base dataclass inherited by both DeployFixCallOutBundle and DeployMitigationCallOutBundle.

Sharing the monitoring/prioritization seams via a base dataclass follows BT-23-003 (domain bundle pattern) and avoids field duplication across two closely-related bundles.
BT-20-008 SHOULD A create_deploy_tree combinator factory SHOULD compose fix and mitigation arms into an overarching DeployOrMitigateBT Fallback (fix arm first).

A deployer that has a fix must deploy it, and use a mitigation only when it cannot. A combinator with the fix arm first shows that preference in one tree. Thus no call site can put the two deploy trees in the incorrect order.

Call-Out Point Backend Selection

Requirements for how running code selects and injects backend factories into BT tree builders. Covers the three-mode model (deterministic / stochastic / real), the domain bundle dataclass pattern, pre-built singletons, the CallOutBackendFactory Protocol, and the default direction rule. Derived from the planning session for issue #1631.

ID Priority Requirement Related
BT-23-001 MUST Call-out point backends MUST be organised into three logical modes. These are DETERMINISTIC (AlwaysSucceed or AlwaysFail, from the ceiling or floor of stochastic probabilities), STOCHASTIC (probabilistic fuzzer classes), and REAL (production implementations).

Three named modes keep the choice of backend explicit: a fixed answer, a simulated answer, or a production answer. The mode names also show the intended path from DETERMINISTIC to REAL as the production implementations become available.
BT-23-014 MUST The DETERMINISTIC mode MUST be the default for all tree builders, integration tests, and demo scenarios that do not explicitly opt into STOCHASTIC or REAL.

Deterministic defaults make integration tests and demo scenarios repeatable, with no configuration at each call site. A stochastic default makes CI non-deterministic. The probabilistic mode is useful only for simulation and fuzz tests.
Extends: BT-23-001
BT-23-002 MUST When the stochastic success probability p > 0.5, the DETERMINISTIC backend for that call-out point MUST be AlwaysSucceed.

Grounding the deterministic backend in the stochastic probability preserves the semantic intent of each node. Nodes that the simulation expects to usually succeed map to AlwaysSucceed so that deterministic demo scenarios make forward protocol progress.
Refines: BT-23-001
BT-23-006 MUST When the stochastic success probability p < 0.5, the DETERMINISTIC backend for that call-out point MUST be AlwaysFail.

Nodes that the simulation expects to usually fail map to AlwaysFail, preserving the semantic intent that such a call-out point is unlikely to succeed in a realistic scenario.
BT-23-007 MUST When the stochastic success probability p == 0.5, the DETERMINISTIC backend for that call-out point MUST be AlwaysSucceed (happy-path default).

The p == 0.5 tie-breaking rule selects the happy-path direction so that deterministic demo scenarios make forward protocol progress when the simulation assigns equal probability to success and failure.
BT-23-003 MUST Call-out point factories for a domain area MUST be collected into a domain bundle — a frozen @dataclass (one per domain area) whose fields are typed CallOutBackendFactory values.

Individual per-node factory kwargs accumulate quickly (a tree builder may have 5–10 call-out points); a bundle dataclass keeps the tree builder signature clean while enforcing completeness (all fields must be supplied). The frozen constraint prevents accidental mutation after construction.
Extends: BT-18-004 — Replaces the individual factory-kwarg API with the bundle API.
BT-23-008 MUST The domain bundle dataclass and its DETERMINISTIC singleton (e.g., VALIDATION_DETERMINISTIC) MUST be defined in the core layer (vultron/core/behaviors/call_out/bundles/<domain>.py).

The DETERMINISTIC bundle is the default backend that lets the protocol move forward. A real actor can use it in production before a capability implementation is available. Thus a core tree builder must find its default without access to the simulation layer. If the bundle is in vultron/demo/, core depends on demo (BT-16-001, BTND-04-002).
BT-23-009 MUST The STOCHASTIC singleton (e.g., VALIDATION_STOCHASTIC) MUST be defined in the simulation layer (vultron/demo/fuzzer/bundles/<domain>.py).

The probabilistic STOCHASTIC wiring is a simulation artefact; keeping it in vultron/demo/ respects the BT-16-001 rule that simulation artefacts do not appear in vultron/core/.
BT-23-010 MUST Tree builders that accept call-out factories MUST accept the bundle as a single typed parameter (e.g., call_out: ValidationCallOutBundle) rather than individual per-node factory kwargs.

A bundle parameter keeps the tree builder signature clean and enforces completeness — all fields must be supplied, making missing call-out points a static type error rather than a silent runtime omission.
BT-23-011 MUST Tree builders MUST default the bundle parameter to the core DETERMINISTIC singleton without importing from vultron/demo/ (per BT-16-001 and ARCH-01-001).

Pre-built singletons avoid non-DRY construction in every demo script and test fixture. Defaulting to the core DETERMINISTIC singleton ensures the tree builder has no simulation-layer import dependency.
See also: ARCH-01-001 — context for the reader
See also: BT-16-001 — context for the reader
BT-23-004 MUST The CallOutBackendFactory type MUST be defined as a typing.Protocol, not as a bare Callable type alias.

A Protocol produces IDE completion and pyright/mypy enforcement of the factory signature without requiring runtime registration overhead. Duck- typing via Protocol is consistent with how other ports in the codebase are typed (vultron/core/ports/use_case.py), and avoids the coupling risk of a central registry (name-key typos are silent runtime failures rather than static errors).
Extends: BT-18-004
BT-23-015 MUST The CallOutBackendFactory Protocol MUST declare a single call method accepting name: str and returning py_trees.behaviour.Behaviour.

One fixed call signature lets every tree builder construct any backend the same way. Static type checking (mypy/pyright) validates that signature, so no central registration or base class inheritance is required.
Extends: BT-23-004
BT-23-005 SHOULD Domain bundle classes SHOULD follow the naming convention CallOutBundle, for example ValidationCallOutBundle or EmbargoCallOutBundle.

Consistent naming makes the available bundles discoverable without reading the implementation. BT-23-008 and BT-23-009 say in which layer each part of a bundle lives.
Extends: BT-23-003
BT-23-016 SHOULD The pre-built bundle singletons SHOULD be named _DETERMINISTIC and _STOCHASTIC, for example VALIDATION_DETERMINISTIC or EMBARGO_STOCHASTIC.

When each singleton name carries its domain and its mode, a reader sees which backend a tree builder gets without reading the bundle.
BT-23-017 MAY The module vultron/demo/fuzzer/bundles/.py MAY re-export the core dataclass and DETERMINISTIC singleton for backward-compatible import paths.

Code that imports a bundle from its earlier simulation-layer path keeps working, while the definitions stay in core (BT-23-008).
BT-23-012 MUST A call-out gate whose permissive backend would let a party other than the Case Owner unilaterally cause canonical case-state adoption or embargo teardown on the received side MUST default to the conservative (floor) backend regardless of its stochastic success probability. The ceiling/floor rules BT-23-002, BT-23-006, and BT-23-007 apply only to gates that do NOT have this property.

BT-23-002, BT-23-006 and BT-23-007 select the DETERMINISTIC backend from the success probability of the simulation. For a security-significant gate, this gives a high-probability node the permissive AlwaysSucceed. Then, by default, a party that is not the Case Owner can adopt case state or end an embargo. For such a gate, a permissive default is a protocol-security risk, not a prototype convenience. Thus the floor (the most restrictive backend with correct semantics) is the default. A permissive backend is an explicit operator choice that the operator must document (ADR-0076). Because the rule is general, each gate author applies it when the gate is added, and an audit does not have to find it later. notes/call-out-configuration.md tells which gates qualify. It also tells why similar gates do not qualify, for example the trigger-side EmbargoExitPolicyGuard. This rule sets only the default posture. RSH-07-004 (ADR-0080) tells how to compose a qualifying gate.
Supersedes: BT-23-002 — Carves out security-significant gates from the p>0.5 → AlwaysSucceed rule; the same carve-out applies to BT-23-006 and BT-23-007.

Derives from: RSH-07-001 — The conservative default follows from RSH-07-001's rule that adopting a non-owner's report needs the Case Owner's authorization by default.
Supersedes: BT-23-006
Supersedes: BT-23-007
BT-23-013 MUST For a capability that declares output ports, the DETERMINISTIC backend MUST give a type-conformant value for each declared port when it answers yes. Where BT-23-002 or BT-23-007 also applies, this rule overrides their choice of AlwaysSucceed by class but not the yes or no direction they set.

BT-23-002 and BT-23-007 select the deterministic backend so that deterministic demo scenarios move the protocol forward. For a capability that makes data, a constant SUCCESS with no data prevents that. The capability reports success, the downstream gate reads a missing key, and the arm does nothing. To move forward through an arm that needs data, the tree must have the data. Thus the status direction alone does not fully specify the default. The failure is silent, because a downstream read declared optional gives FAILURE, not an error. Thus the rule puts the obligation on the default. A reviewer does not have to find the problem by chance. BT-18-012 lets core read the declared contract, so a conforming default is possible. The same obligation applies to a STOCHASTIC backend under BT-18-003. This includes the generic WeightedBehavior backends for production-only domains that have no named fuzzer node.
Supersedes: BT-23-002 — BT-23-002 names AlwaysSucceed by class; for a data-producing capability BT-23-013 substitutes a contract-honouring backend in the same SUCCESS direction. The same constraint applies to BT-23-007.

Refines: BT-18-002 — BT-23-013 applies BT-18-002 to the specific backend that BT-23-001 makes the default everywhere.

Supersedes: BT-23-007

Participant Suggestion Port

Requirements for the one interface through which an actor asks who else should take part in a case, whether the question comes from a call-out inside a tree or from a call-in Sentinel outside core (ADR-0186).

ID Priority Requirement Related
BT-24-001 MUST An actor that asks who else should take part in a case MUST ask through the one participant-suggestion driven port, whether a call-out inside a tree or a call-in Sentinel outside core asks the question.

Both callers want the same answer. One port means one adapter serves both, and the answer shape is stated once in core.
Refines: BT-20-003
Refines: BT-20-013
BT-24-002 MUST The participant-suggestion port MUST receive a core-owned suggestion context projected from the case, not the case itself.

Much of a case is under embargo. An adapter cannot pass on information it never receives, so the port's signature is where the disclosure limit holds.
BT-24-003 MUST The projection from a case to a suggestion context MUST be defined once, in core.

Which case information leaves the actor is a disclosure decision. Defined once, it is tested once, and widening it is a visible change to a core type rather than a quiet edit inside one adapter or one caller.
Depends on: BT-24-002
BT-24-008 MUST Every caller of the participant-suggestion port MUST reach it through the core projection from a case to a suggestion context (BT-24-003).

A caller that builds its own context bypasses the one disclosure decision, so the limit holds only if no caller can skip the projection.
Depends on: BT-24-003
BT-24-009 MUST The suggestion context MUST be a case profile: a model class whose every field has the name and type of a field of the case, or of an object the case holds, and which builds itself from a case.

A subclass of the case fails open, inheriting every field added to the case later. A profile fails closed, so a new case field reaches the context only when it is declared there. Nested objects are profiled too. The reports' content is the evidence, since a report may name a vendor not yet in the case; each participant keeps its actor id and roles, marking who is already included.
Refines: BT-24-003
BT-24-004 MUST Each suggestion the participant-suggestion port returns MUST carry an actor id, a suggested CVDRole, and a rationale. An answer with no suggestions is valid.

The id and role are what suggest-actor-to-case needs. The rationale lets the Case Owner judge the suggestion, because a suggestion is not a definitive fact.
BT-24-005 SHOULD A participant-suggestion adapter SHOULD prefer suggesting a party that turns out not to be needed over omitting a party that is.

In CVD an uninformed affected party is the costlier error. The Case Owner still approves each suggestion, so an extra one costs a decision, not a disclosure.
BT-24-006 MUST NOT A suggestion MUST NOT carry invitation timing. The actor that receives the suggestions schedules each invite.

The suggester answers who and why. When to invite depends on the invitee's published embargo policy and the case's remaining embargo, which the receiver holds and the suggester does not need.
BT-24-007 MUST Demo scenarios and tests that use the participant-suggestion port MUST answer it with a static adapter that reads a candidate table the scenario declares.

The prototype needs the port's shape, not a directory or recommender service. A declared table makes the answer deterministic (BT-23-014) and keeps the demo's suggested parties visible in the scenario itself.
Uses definition from: BT-23-014

One Fixed-Shape Tree per Act

Requirements for the shape and lifetime of a behavior tree: its shape is fixed by the act, data reaches its nodes through the blackboard, every act runs one tree, and a run releases every blackboard client it registered (ADR-0207).

ID Priority Requirement Related
BT-25-001 MUST NOT A BT node, and any function or method a node's update() reaches, MUST NOT call BTBridge.execute_with_setup or tick a tree of its own.

A nested run can hide the inner tree's internal error behind the outer node's verdict unless each site carries it across by hand, and it hides its subtree from a walk over the tree, so nothing can release or inspect it whole.
Extends: CLP-10-005
BT-25-002 MUST A step whose count is known only at run time MUST be one subtree under a loop. The loop ticks the subtree once for each item of a work list on the blackboard, and stops at the first item whose subtree fails.

The tree keeps one shape whatever the count, so no node builds a tree while a tree runs.
Refines: BT-25-001
BT-25-003 MUST A subtree under a work-list loop MUST read each per-item value from the blackboard. It does not take the value from its factory or a node constructor.

A value baked into a constructor fixes the subtree to one item, which forces a new subtree for each item.
Implements: BT-25-002
BT-25-004 MUST Before it returns, a tree run MUST release every blackboard client that its nodes or its runner registered, on every outcome. The release clears no stored key.

Blackboard.clients is process-global and py_trees releases nothing itself, so an unreleased client lives for the whole process. Clearing stored keys would undo the bridge's restore (BT-17-007).
Depends on: BT-25-001
BT-25-005 MUST NOT A tree MUST NOT be run for an act other than the one it was built for.

A node object that outlives its act carries its instance attributes into the next one, which is hidden process-wide state.
BT-25-006 MUST A tree factory MUST declare the per-act keys (BTND-01-008) its tree needs before any of its nodes runs.

The declaration is the tree's input contract: given these values, the tree's logic completes its act. A reader, a test or a published behavior spec can then state what a tree needs without reading its nodes.
Uses definition from: BTND-01-008
BT-25-007 MUST Before the first tick, the received-tree runner and the trigger-tree runner MUST seed each declared key (BT-25-006) whose value the act's event or trigger request carries.

Copying a value the message or request carries reads no store, so the runner stays free of DataLayer reads (ADR-0195), and no factory has to bake the value into a node.
Depends on: BT-25-006
BT-25-008 MUST NOT A runner MUST NOT tick a tree when a key the tree declares (BT-25-006) has no value and no node of the tree publishes it. The runner raises a wiring error instead.

A missing input is a programming error in the seeding or the declaration, not a protocol condition. Ticking anyway would let a node read an absent value and report a refusal that no message caused.
Refines: BT-25-007
Uses definition from: BT-25-006
BT-25-009 MUST A per-act value that only a DataLayer read can find MUST be published by a lookup node in the tree that needs it, never read before the tree runs.

A use case and its runner read no DataLayer before the run, in a received tree (ADR-0195) and in a trigger tree alike (ADR-0207). The lookup can also fail, and only a node can turn that failure into a declared verdict with its reason. In a trigger tree, a lookup that finds nothing keeps the trigger's current not-found or refused result; BT-25-010 covers received trees only.
Refines: BT-25-007
BT-25-010 MUST In a received tree, a lookup node (BT-25-009) that finds no value MUST declare a refusal whose reason names the missing object and the requirement it cites.

The runner reads a refusal only from a node's declaration (ADR-0195). A lookup that fails without one would be read as an unexplained failure.
Refines: BT-25-009
BT-25-011 MUST Each per-act key a tree declares (BT-25-006) MUST have one source in that tree: the runner's seed (BT-25-007) or one publishing node (BT-25-009), never both.

A key with two sources is the dual channel BTND-01-007 forbids at one node, raised to the tree. A seeded value would hide the value a lookup node found, or the reverse, depending on tick order.
Extends: BTND-01-007
Uses definition from: BT-25-006
See also: BT-25-007 — names the runner's seed, one of the two sources this rule keeps apart
See also: BT-25-009 — names the publishing lookup node, the other source this rule keeps apart

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

Node Parameterization

ID Priority Requirement Related
BTND-01-001 MUST NOT A BT node MUST NOT hard-code an actor identity, a CVD role, a case ID or any other value that varies by usage site.

Hard-coded context values prevent reuse across actors or scenarios and couple the node to a single workflow.
BTND-01-002 MUST NOT A BT node MUST NOT read its actor identity, case ID or CVD role from implicit ambient context. Environment variables and module-level globals are such context.

A value that a node reads from the environment or from a global is a hidden input. Several actors can run in one process. Thus ambient context can give the identity or the case of one actor to the tree of a different actor. A test also cannot set such a value without a change to shared state. When all inputs are explicit, the behavior of a node depends only on what its tree gives it.
BTND-01-003 MUST When a BT node name is derived from a parameterized value (e.g., role or actor ID), the name MUST be constructed from that parameter at instantiation time, not hard-coded as a string literal.

Tree traces and logs show node names. If a parameterized node uses a literal name, all its instances have the same label. Then a trace cannot show which role or actor each instance served.
Refines: BTND-01-001
BTND-01-005 MUST A BT node MUST receive each variable input through a constructor parameter or the documented blackboard interface.

These two channels are the inputs that a tree and its tests can see and set. An input that arrives any other way is hidden, and a test cannot control it.
Extends: BTND-01-002
BTND-01-006 MUST Some trees find a node's input value only at tick time. Such a node MUST read that value from a declared blackboard input port in every tree that uses it.

A declared port keeps the input visible to the tree and its tests, as BTND-01-005 requires. One channel per node keeps every tree that uses the node alike: a tree that knows the value at build time seeds the port, and a tree that finds it at tick time publishes it from an earlier node. BTND-10-005 applies this rule to the ParticipantStatus write node.
Refines: BTND-01-005
BTND-01-007 MUST A node that reads an input value from a blackboard input port under BTND-01-006 MUST NOT also take that value as a constructor parameter.

A node that takes the value from its constructor and falls back to the port reads the port only when a tree passes no value. A stale port value left by one execution then decides another execution's result, as the shared case ID did before execution-scoped keys. One channel removes that fallback.
Extends: BTND-01-006
BTND-01-008 MUST A BT node MUST read each per-act value it uses from a named blackboard key. A per-act value varies with the act a tree runs for, such as a case, report, embargo or actor id, or a carried object.

A tree whose nodes read their data from keys has one shape for every act of its kind. It can then run as a subtree, a work-list loop body or a trigger tree unchanged, and a reader can state its logic as "given these inputs, do this" (ADR-0207).
Extends: BTND-01-006
BTND-01-009 MUST NOT A BT node constructor, and a tree factory, MUST NOT take a per-act value (BTND-01-008) as a parameter. A constructor takes only configuration, such as a name, a port name, a CVD role, a declared state or a child node.

A per-act value baked in at build time makes the tree's shape depend on its data. Such a tree must be rebuilt for each item, which pushed nodes into nested runs (ADR-0207). A value fixed at build time also forces a store read before the tree runs whenever the value is found in the store (ADR-0195).
Implements: BTND-01-008
Constrains: BT-17-011

Composability and Reuse

ID Priority Requirement Related
BTND-02-001 MUST Logic in two or more BT nodes or subtrees MUST be extracted into one shared, parameterized node or factory in a neutral shared module (BTND-04-005).

Copies of the same logic drift apart, because each copy gets its own fixes. Then two trees enforce different rules for the same protocol step. One shared node gives one version to test and to change.
Uses definition from: BTND-04-005
BTND-02-002 SHOULD Each BT subtree SHOULD be independently triggerable as a use-case entry point AND composable as a child of a larger subtree.

This is the "fractal composability" pattern. Subtrees that can only be used one way are candidates for refactoring.
BTND-02-003 SHOULD New BT subtrees SHOULD be verified against notes/vultron-bt.txt (the canonical simulation BT structure) to confirm structural correspondence before committing.

The canonical simulation tree is the reference design for protocol behavior. A check before commit finds a subtree that does not agree with that design while the change is still small. After other trees depend on the subtree, the correction costs more.
Verifies: BT-06-002
BTND-02-004 SHOULD A shared BT node or subtree that models a generic operation (e.g., "create a case participant with any role") SHOULD replace all role-specific one-off variants (e.g., CreateReporterParticipantNode, CreateVendorParticipantNode) once the shared version is available.

Reduces maintenance surface; fixes and improvements apply consistently across all use sites.

Blackboard Interface Contracts

ID Priority Requirement Related
BTND-03-001 MUST Each BT node that reads from or writes to the py_trees blackboard MUST declare all blackboard keys it uses in its setup() method via register_key().

Undeclared blackboard reads create hidden dependencies that break composability and make tests fragile.
BTND-03-002 MUST NOT A BT node MUST NOT read a blackboard key that was not registered with at least READ access in setup().

Registration is the contract that a node declares with the blackboard, and py_trees uses this contract to enforce access. If a node reads a key that it did not register, one of two problems occurs. The read fails at tick time, or the read hides a dependency that a reader of setup() cannot see.
Refines: BTND-03-001
BTND-03-003 SHOULD A BT node's docstring SHOULD document all blackboard keys it reads and writes, including the expected type and the node that produces the value for each READ key.

The docstring tells a reader the data flow of a node without the code. When the docstring gives the type and the producer of each key, the reader sees which node must run first. The reader also sees what a consumer can expect. Thus a broken handoff is easier to find.
BTND-03-004 MUST A BT node that writes an inter-node handoff key MUST namespace it by the execution-scoped correlation ID of its tree instance, as {noun}_{id_segment}. An inter-node handoff key is a blackboard key that one node writes and a downstream sibling in the same tree reads. For an HTTP URI, id_segment is recommendation_id.split('/')[-1]. For a URN ID, it is the last colon-delimited segment.

The py_trees blackboard is global to the process. A tree factory can run concurrently, for example for two Offer(Actor)[target=VulnerabilityCase] messages that the actor handles in parallel. Then both tree instances share one blackboard namespace. The first instance can write a flat key such as suggested_roles, and the second instance can overwrite it before the first instance reads it. Then the Case Owner gets the wrong role list. A key that contains the execution-scoped ID, such as suggested_roles_abc123, gives each execution its own key. See notes/bt-pitfalls.md § "Namespaced Inter-Node Handoff Keys".
Refines: BTND-03-008
BTND-03-005 MUST NOT Blackboard keys MUST NOT contain forward-slash characters.

py_trees parses forward-slashes as namespacing separators; a key containing / silently creates a sub-namespace and will not be found by flat-key readers.
Constrains: BTND-03-004
BTND-03-008 MUST Blackboard keys MUST follow the {noun}_{id_segment} naming convention where the noun names the value and id_segment is the execution-scoped correlation ID (last path or colon-delimited segment). Flat, unscoped keys (e.g., result, status) are only permitted for top-level handoff keys that are consumed in the same tick cycle and cannot collide.

The {noun}_{id_segment} convention generalizes BTND-03-004 to all keys, not just inter-node handoffs.
BTND-03-006 MUST A decomposed BT leaf node that meets a domain-layer error MUST write the error to the result_out["error"] blackboard key before it returns FAILURE.

Without a written error key the bridge layer sees only FAILURE with no diagnostic context; the error is silently swallowed. Writing to result_out["error"] ensures the error propagates to the caller via the result channel even when the BT stops traversal at the failing leaf.
BTND-03-007 MUST A decomposed BT leaf node MUST catch a KeyError for a missing blackboard key in its update() method and return FAILURE. The KeyError then never reaches the bridge layer.

A KeyError propagating to the bridge results in an unhandled 500-level error for the caller. At the leaf level the semantics of "key not present" are known — this is a precondition failure, not an unexpected crash, so FAILURE is the correct BT response.
BTND-03-009 MUST A new BT node in vultron/core/behaviors/ MUST subclass DataLayerConditionWithPorts or DataLayerActionWithPorts from helpers/, not DataLayerCondition or DataLayerAction.

Typed port declarations are machine-readable and are at the class level. They are the one source of truth for the data-flow contract of a node. The imperative register_key() approach puts declarations in setup(), initialise() and update(). py_trees 2.6 and later treats a ports class without both attributes as abstract, and does not instantiate it. Thus an accessor override is not a valid declaration (ADR-0044).
Supersedes: BTND-03-001
BTND-03-010 MUST A DataLayerConditionWithPorts or DataLayerActionWithPorts subclass MUST call setup_ports() in its setup() method with port remappings {"datalayer": "/datalayer", "actor_id": "/actor_id"} (plus "trigger_activity_factory": "/trigger_activity_factory" for action nodes). These absolute-path remappings wire the node's declared ports to the flat keys written by BTBridge.setup_tree().

The BehaviourWithPorts default namespace scopes port keys under the node's subtree path, which does not match the flat /datalayer and /actor_id keys that BTBridge.setup_tree() writes. Explicit absolute-path remappings are required for compatibility. The base classes DataLayerConditionWithPorts and DataLayerActionWithPorts implement this in their own setup() so subclasses that do not add extra ports need not override setup().
Extends: BTND-03-009
BTND-03-011 MUST A DataLayerConditionWithPorts or DataLayerActionWithPorts subclass MUST read injected values via get_input(port_name) in initialise() (not via direct self.blackboard.<key> attribute access). A missing required port raises NoDataAvailable when get_input() is first called in initialise() — at the start of the first tick, not during setup().

Direct blackboard attribute access bypasses the typed port layer and its early error detection. Using get_input() preserves type checking and NoDataAvailable detection for required ports.
Extends: BTND-03-009
BTND-03-012 MUST A DataLayerActionWithPorts subclass MUST declare each handoff key it writes in OUTPUT_PORTS and write it with self._set_output(), never by direct blackboard assignment.

Declaring output ports in OUTPUT_PORTS makes the node's write contract explicit and machine-readable, consistent with the input-port convention from BTND-03-009/BTND-03-011. Using _set_output() routes writes through the typed port layer so the framework enforces that only declared output keys are written.
Extends: BTND-03-009
BTND-03-013 MUST An output port with an execution-scoped physical key (BTND-03-004) MUST have a stable logical name in OUTPUT_PORTS that is only its {noun} part. An example physical key is suggested_roles_abc123.

OUTPUT_PORTS is a class attribute with no access to instance state, so execution-scoped physical keys (computed in __init__) cannot be declared there directly. Declaring a stable logical name and binding the physical key in setup() separates the interface (class attribute) from the execution-time binding (instance method), preserving BTND-03-004 concurrent-execution safety while enabling typed port declarations. Validated against py_trees.ports.PortsMixin.setup_ports() remapping semantics.
Extends: BTND-03-012
Uses definition from: BTND-03-004
BTND-03-014 MUST Every node in a tree that reads or writes an inter-node handoff value MUST use the same namespaced key for that value.

A namespaced key protects a handoff only when the writer and every reader agree on it. If one node uses a different key, the reader finds no value, or it finds the value of another execution.
Extends: BTND-03-004
BTND-03-015 MUST After a decomposed BT leaf node writes a domain-layer error to result_out["error"], execute() MUST re-raise the original exception.

The bridge layer maps the original exception to the matching HTTP error response. If execute() does not re-raise it, the caller gets a generic failure and loses the error type.
Extends: BTND-03-006
BTND-03-016 MUST The FAILURE that a decomposed BT leaf node returns for a missing blackboard key MUST carry a diagnostic message that names the missing key.

A bare FAILURE does not tell a reader which precondition was absent. The key name points the reader to the node that should have written it.
Extends: BTND-03-007
BTND-03-017 MUST The INPUT_PORTS and OUTPUT_PORTS class attributes of a BT node in vultron/core/behaviors/ MUST declare every port that the node reads or writes.

These typed class attributes are the formal blackboard contract of the node. A port that they do not declare is a hidden input or output, which a reader and a tool cannot see.
Extends: BTND-03-009
BTND-03-018 MUST NOT A ports node subclass extends the ports of its parent by spreading the parent attribute, as in {**Parent.INPUT_PORTS, ...}. It MUST NOT override the input_ports() or output_ports() accessors.

py_trees 2.6 and later treats a ports class without both attributes as abstract, and does not instantiate it. Thus an accessor override is not a valid port declaration (ADR-0044).
Extends: BTND-03-009
BTND-03-019 MUST A DataLayerActionWithPorts subclass MUST include its output port remappings in the port_remappings dict that it passes to setup_ports(), usually through _domain_port_remappings().

A declared output port reaches its blackboard key only through a remapping. Without it, _set_output() writes to a key that no downstream reader looks at.
Extends: BTND-03-012
BTND-03-020 MUST A node whose output port has an execution-scoped physical key MUST bind that key by overriding setup() to pass port_remappings={"logical_name": physical_key} to setup_ports().

OUTPUT_PORTS is a class attribute with no access to instance state, so it cannot name a key computed in __init__. The binding in setup() connects the stable logical name, which is the public contract, to the key of each execution.
Extends: BTND-03-013
BTND-03-021 MUST A node's read of a blackboard value that is not of its port's declared data_type MUST fail the whole tree run, rather than return the value as absent.

A wrong-typed value is a wiring error, not a protocol condition, so the tree has no correct partial outcome to report. Read as absent, the value would let a caller that takes None to mean "not supplied" go on with a silent default, which ARCH-15 forbids. A node-local FAILURE would hand control to a Selector's fallback arm, the same hazard a refusal arm avoids by raising.
Refines: BTND-03-011
BTND-03-022 MUST Every blackboard key that carries a per-act value (BTND-01-008) MUST be named in one key vocabulary module under vultron/core/behaviors/, with the type and the meaning of its value.

One vocabulary gives every tree the same name for the same input. A node then declares the keys it reads, and a reader can find what each one means without reading the trees that seed it.
Uses definition from: BTND-01-008

Module Ownership

ID Priority Requirement Related
BTND-04-001 MUST NOT A domain-specific module in vultron/core/behaviors/ MUST NOT import BT nodes from a sibling domain module.

Cross-domain node imports create tight coupling and circular-import risk. Neutral shared ownership makes the dependency structure explicit.
BTND-04-002 MUST NOT BT nodes MUST NOT import from vultron/demo/ or any other demo-layer module. Demo-specific context (step descriptions, demo loggers, demo flags) belongs in demo scripts, not in BT nodes.

The demo layer is outside core and depends on core. A behavior node that imports demo code reverses that dependency. It also puts demo-only context into the protocol logic. A deployment that ships core without the demos then fails.
BTND-04-003 MUST NOT A behaviors/ module MUST NOT import from a use_cases/ module.

Importing use-cases from behaviors inverts the composition hierarchy (behaviors are the implementation layer of use-cases, not their consumers) and introduces circular imports when use-cases inject behaviors via factories.
BTND-04-004 MUST Logic shared between behaviors/ and use_cases/ MUST be extracted to a common helper in vultron/core/ or vultron/core/behaviors/helpers/.

behaviors/ must not import use_cases/ (BTND-04-003). Thus logic that both layers need must be in a location that both layers can import. Without that location, only two choices remain: an import that breaks the layering, or a second copy that drifts.
Derives from: BTND-04-003
BTND-04-005 MUST A BT node or subtree that more than one domain module uses MUST be defined in helpers/ or another purpose-built shared module in vultron/core/behaviors/. Two such domain modules are case/ and report/.

A neutral shared module gives each domain module a place to import from that is not a sibling. The dependency structure then stays explicit, with no cross-domain imports and no circular-import risk.
Implements: BTND-04-001
BTND-04-006 MUST NOT A BT node MUST NOT import a use-case class or function.

Behaviors implement use cases, so a node that imports a use case inverts the composition hierarchy. It also makes a circular import when the use case injects the behavior through a factory.
Refines: BTND-04-003

Actor Configuration for Participant Nodes

ID Priority Requirement Related
BTND-05-001 MUST The CVDRoles enum MUST include a CASE_OWNER flag value representing the actor who owns and manages a VulnerabilityCase.

Case ownership is a protocol-significant relationship distinct from the CVD roles (VENDOR, COORDINATOR, etc.). When a vendor or coordinator receives a report and creates a case, they are both the receiving CVD actor (VENDOR or COORDINATOR) and the Case Owner. Representing this explicitly avoids hardcoding the assumption that the case creator is always a vendor.
BTND-05-002 MUST The BT node for creating the initial case participant MUST be role-agnostic; the correct node for this purpose is AddOwnerParticipantNode, which takes the Case Owner's additional roles from ActorConfig.default_case_roles.

"Vendor" is a demo-specific assumption. In the general protocol a coordinator, deployer, or other role may equally receive a report and become the Case Owner.
Refines: BTND-01-001
BTND-05-003 MUST Participant-creation BT nodes MUST build and attach the CaseParticipant record through the shared _create_and_attach_participant helper (vultron/core/behaviors/case/nodes/participant/common.py) rather than re-implementing create-and-attach per flow. The helper carries no status or embargo-consent policy; each seating flow (Case Owner, inert invitee, reporter) supplies its own roles and initial status. No role-specific participant-creation subclasses or alias names are permitted.

Participant creation differs by protocol moment — case creation, stub-Invite seating (CM-11-006), reporter seating — not by role. The invitee flow must seat an inert, non-signatory participant (ADR-0114), so a single composite creation node bundling embargo-signatory seeding (the retired CreateCaseParticipantNode) could not serve every flow. Centralizing the policy-free create-and-attach in _create_and_attach_participant keeps the mechanism DRY without forcing an incompatible policy.
BTND-05-004 MUST The CVDRole enum MUST include a CVE_NUMBERING_AUTHORITY value representing a participant that holds CVE Numbering Authority (CNA) status.

Multiple participants in an MPCVD case may independently be CNAs (e.g., a vendor CNA and a coordinator CNA). The IsIDAssignmentAuthority BT node checks whether a participant holds this role as a static capability check; IdAssignable evaluates whether the CNA's scope rules cover the specific vulnerability. Without a CVE_NUMBERING_AUTHORITY role in CVDRole, the protocol has no way to represent CNA status, route ID-assignment decision nodes to the correct participant(s), or distinguish CNA participants from non-CNA participants in case actor lists. CVE_NUMBERING_AUTHORITY is orthogonal to all other CVD roles — a VENDOR, COORDINATOR, or any participant may independently hold it.
BTND-05-005 MUST NOT The BT node for creating the initial case participant MUST NOT assume any specific CVD role (e.g., Vendor).

Any CVD actor (coordinator, deployer, vendor, etc.) may receive a report and become the Case Owner; hardcoding a role couples the node to a single scenario.
BTND-05-006 MUST The BT node for creating the initial case participant MUST treat the actor as the Case Owner regardless of their CVD role(s).

Case ownership is orthogonal to CVD role. The node must apply the CASE_OWNER flag without requiring or checking any specific CVD role value.
BTND-05-007 SHOULD CVE eligibility checking SHOULD be implemented as a single EvaluateCveEligibility Evaluator call-out point rather than as multiple individual call-out points for each eligibility criterion.

CVE eligibility is one logical capability: a set of criteria evaluated as a unit against a specific version of the CNA Operational Rules. Treating each criterion as an independent call-out point misrepresents the substitution unit — when the rules are updated, all criteria change together, not independently. A single Evaluator call-out correctly models the "replace the whole eligibility check" seam (ADR-0071).
BTND-05-008 SHOULD The EvaluateCveEligibility call-out point SHOULD be grounded in the CNA Operational Rules edition endorsed by the current spec as the conformance baseline. The reference implementation follows CNA Operational Rules v4.1.0. Adopting a newer edition requires updating both this spec and the implementing call-out factory.

Pinning the eligibility logic to a specific rules edition in the implementation (not the RFC) avoids coupling the protocol spec to an independently-versioned external document's release cycle, while remaining transparent about which edition serves as the conformance baseline (ADR-0071).
Extends: BTND-05-007

Idiomatic BT Construction Patterns

ID Priority Requirement Related
BTND-06-001 SHOULD Stateful BT nodes SHOULD use the implicit sequence pattern: a Fallback whose first child checks whether the goal is already achieved (the postcondition), and whose remaining children perform the work only when the goal has not yet been reached.

Automatically makes nodes idempotent and reactive. Re-ticking a satisfied node costs only a cheap condition check. This is the dominant pattern throughout vultron/bt/.
BTND-06-002 SHOULD When a Sequence contains multiple actions, each action that may already be complete SHOULD be paired with its success condition via a Fallback, making the explicit success condition visible in the tree.

Improves readability and correctness. Readers can determine the success criterion of each step from the tree alone, without reading action implementations.
BTND-06-003 SHOULD Every BT node that performs a protocol state transition (RM/EM/CS state machine update, emitting an AS2 activity, or creating/updating a domain object) SHOULD follow the PPA (Postcondition–Precondition–Action) structure: Fallback(Postcondition, Sequence(Precondition1, …, PreconditionN, Action)).

PPA is the canonical "unit cell" of idiomatic BT design. It makes the node's contract (what it requires and what it guarantees) explicit and machine-readable from the tree structure.
Refines: BTND-06-001
BTND-06-004 MAY Multi-step workflows where each step has its own preconditions that may need to be achieved MAY be constructed using back-chaining: start with the goal condition, find the PPA whose postcondition matches, and recursively substitute failing preconditions with their own PPAs.

Back-chaining produces fully reactive, goal-directed trees where intermediate states are automatically recovered on failure.
Uses definition from: BTND-06-003
BTND-06-005 MUST Before any irreversible or protocol-significant action, a safety guard condition MUST be the first child of the enclosing Sequence, so that the action is skipped when the guard fails.

Prevents unsafe state transitions when the world changes between ticks. In a multi-party protocol, another actor may change shared state at any time.
BTND-06-006 MAY Memory composites (memory=True in py_trees) MAY be used only in contexts that are fully deterministic and non-reactive: no external actor can undo a child's outcome between ticks, and the agent operates in a closed-loop, human-supervised environment.

A memory composite does not tick again a child that succeeded on an earlier tick. Between ticks, a message from a different actor can make the result of that child false. Then the tree acts on a success that is not true. The skip is safe only in a closed, deterministic setting.
BTND-06-007 SHOULD A behavior SHOULD be implemented as a leaf node when the action is atomic and has no observable sub-steps.

Leaf nodes are the appropriate granularity for indivisible actions; decomposing them further adds structural complexity without improving testability.
BTND-06-008 MUST Code that writes to a memory=False py_trees Sequence MUST be written assuming that any child's writes to the blackboard are immediately visible to subsequent children but are NOT rolled back if a later child returns FAILURE. A memory=False Sequence is non-transactional: partial side-effects from earlier children survive the composite's final FAILURE status.

The py_trees memory=False Sequence restarts from the first child on each tick, but it does NOT undo blackboard writes made by children in previous ticks or earlier in the same tick. This surprises developers who expect Sequence failure to be atomic. The correct pattern for atomic multi-write operations is a single leaf node that performs all writes.
BTND-06-009 SHOULD A behavior SHOULD be decomposed into a subtree when it can be split into independently verifiable pre/post-condition pairs.

Decomposing into subtrees with explicit pre/post-condition pairs makes each step individually testable and follows the PPA pattern (BTND-06-003).
BTND-06-010 SHOULD A subtree SHOULD be extracted when the same multi-step pattern appears in more than one place (see BTND-02-001).

Extracting repeated patterns into a shared subtree reduces duplication and ensures fixes and improvements apply consistently across all use sites.
See also: BTND-02-001 — context for the reader

BT Node Module Organization

ID Priority Requirement Related
BTND-07-001 MUST BT node classes for a given protocol step MUST be organized into a nodes/ subpackage rather than a single flat nodes.py module. This applies to all BT-bearing process areas in vultron/core/behaviors/ regardless of current node count or file size.

A flat nodes.py becomes a high-churn, high-blast-radius file where every change — regardless of which workflow step it touches — modifies the same module. Applying the nodes/ subpackage pattern uniformly (not just when a file grows large) keeps the hierarchy consistent and prevents gradual accumulation that creates a large-file problem later.
BTND-07-006 MUST Within a nodes/ subpackage, submodules MUST be grouped by semantic concern (e.g., conditions.py, case_setup.py, participant.py, embargo.py, communication.py, lifecycle.py).

Grouping by semantic concern reduces diff scope, improves discoverability, and lets reviewers focus on the affected concern in isolation.
Extends: BTND-07-001
BTND-07-007 MUST The nodes/ subpackage __init__.py MUST re-export all public node names to preserve import compatibility with callers.

Callers import node names from the package. When a module splits into a nodes/ subpackage, those imports must continue to work. Thus the package must export each public name that it exported before the split.
Extends: BTND-07-001
BTND-07-003 MUST Each BT-bearing process area directory under vultron/core/behaviors/ MUST keep its tree factory modules apart from its leaf node modules. Tree factory modules are the *_tree.py files at the area root, and they define BT composition and structure. Leaf node modules are the files in the nodes/ subpackage, and they define BT Behaviour subclasses.

Mixing tree factory functions and leaf node class definitions in the same module conflates two separate concerns: composition/structure (how the tree is assembled) and implementation/detail (what each leaf node does). Keeping them in separate modules makes the tree structure immediately readable without navigating past implementation details, and lets each concern evolve independently without cross-contaminating diffs.
Extends: BTND-07-001
BTND-07-004 MUST Each BT leaf node module under vultron/core/behaviors/**/nodes/ MUST stay under 500 lines.

Subpackage splits fail when they recreate the same god-module risk in a new file. A hard per-module cap keeps decomposition recursive and auditable.
Refines: CS-18-002
BTND-07-005 MUST Before implementing guard, validation, or factory-call boilerplate in a new BT leaf node's update() method, the implementer MUST search vultron/core/behaviors/ for an existing base class or helper that already provides that boilerplate and inherit or reuse it.

The most common cause of god-node update() methods is copy-paste of guard and factory-call boilerplate from prior nodes. Each copy drifts independently, accumulates line count, and must be fixed separately. A shared base class keeps update() methods to a single try-block orchestration with all logic in overridable hooks, satisfying BTND-07-003 and the DRY principle simultaneously.
BTND-07-008 MUST NOT A new BT leaf node MUST NOT re-implement self.datalayer, self.actor_id, or self.trigger_activity_factory resolution inline; DataLayerAction already provides these lookups.

Inline resolution duplicates logic from DataLayerAction, drifts independently, and increases line count without benefit.
BTND-07-009 MUST A new BT leaf node that follows the standard guard + factory-dispatch + outbox-write pattern MUST subclass an existing emit-node base class (e.g., _EmitCaseActorReportActivityBase) and override _call_factory() rather than writing a new update() from scratch.

Subclassing an existing emit-node base class reuses the standard pattern and ensures fixes and improvements propagate to all subclasses automatically.
BTND-07-010 MUST If no suitable base class exists for the boilerplate pattern needed by a new BT leaf node, the implementer MUST extract the shared pattern into a new base class and document it for future reuse.

Extracting the pattern prevents future copy-paste proliferation and makes the shared abstraction explicit and discoverable.
BTND-07-011 MAY A BT-bearing process area MAY keep supporting files, such as policy.py or update_support.py, at its root beside its tree modules.

Some area code is neither tree composition nor a leaf node, such as a policy table. A place at the area root keeps that code out of both kinds of module.
BTND-07-012 MAY A nodes/ subpackage MAY contain sub-subpackages when a semantic concern grows large, and each one follows the same split recursively.

One level of nodes/ can grow into a new god module. A deeper split by concern keeps each module small, and the same pattern at each depth keeps the layout predictable.
BTND-07-013 MUST This codebase MUST decompose a BT leaf node module that exceeds 500 lines into concern-focused modules or subpackages.

A cap with no remedy leaves an oversized module in place. Decomposition by concern keeps each split module small, and it does not move the same risk into one new file.
Implements: BTND-07-004

Positive-Precondition Condition Node Naming

ID Priority Requirement Related
BTND-08-001 SHOULD A type-dispatch guard in a Selector(Sequence(Condition, Action), AlwaysSuccess) composite SHOULD have a positive name, such as IsFooEventNode, returning SUCCESS when its condition holds.

The Selector(IsNotFoo, ApplyFoo) pattern requires readers to mentally invert the condition to understand when the effect fires, and the IsNotFoo naming implies a guard against Foo when the intent is to apply Foo. Positive-precondition Sequences make intent immediately readable: "if this IS a remove-embargo entry, apply embargo teardown; otherwise skip".
BTND-08-002 SHOULD The AlwaysSuccess fallback in a Selector(Sequence(IsFoo, ApplyFoo), AlwaysSuccess) composite SHOULD be given a descriptive name of the form "<Effect>Skipped" (e.g., "EmbargoEffectsSkipped") so the no-op path is identifiable in BT visualizations and logs.

An unnamed or generically-named AlwaysSuccess node is invisible in tree dumps and log output, making it harder to trace which effect was skipped and why. A descriptive <Effect>Skipped name makes the no-op path explicit and consistent with the existing codebase convention (e.g., "AutoCloseSkippedNotCaseManager", "ValidationSkipped").
Extends: BTND-08-001
BTND-08-003 SHOULD NOT New code SHOULD NOT introduce a negative-guard condition node, such as IsNotFooEventNode, that returns SUCCESS to skip an effect and FAILURE to trigger it.

A negative guard makes a reader invert the condition to see when the effect fires. Its name also suggests a guard against Foo when the intent is to apply Foo.
Extends: BTND-08-001

BT Error Handling Contract

ID Priority Requirement Related
BTND-09-001 MUST A BT helper function MUST raise an exception on error.

If helpers catch their own errors and return sentinels (e.g., None, False), the leaf's update() method cannot distinguish a legitimate None return from a hidden failure. All error information travels via Python's exception mechanism so that the single boundary point (update()) has complete diagnostic context.
BTND-09-002 MUST NOT A BT helper function MUST NOT catch an exception and return a sentinel value, such as None or False, in its place.

A sentinel hides the failure. The caller cannot tell a legitimate None from a failed call, and the error details are lost.
Extends: BTND-09-001
BTND-09-003 MUST The update() method of the owning leaf node MUST be the sole try/except boundary for its helpers. It catches what they raise, writes the error result channel (BTND-03-006) and returns FAILURE.

One boundary gives one place with full diagnostic context, which writes the error and sets the node status. Nested handlers split that work and can swallow an error.
Extends: BTND-09-001
Uses definition from: BTND-03-006

BT Status-Write Node Transition Validation

ID Priority Requirement Related
BTND-10-001 MUST A BT node MUST validate that a ParticipantStatus transition (current_state → target_state) is permitted before it constructs or saves the new dimension object. This applies to a snapshot with a non-None VFD, RM or PXA state. A same-state write (target == current) is permitted as a status confirmation.

The transition() methods of the dimension objects (SDO-02-002) and the is_valid_*_transition() helpers in vultron/core/states/ enforce forward-only state machine rules. But code that constructs VfDimension(state=target) or DDimension(state=target) directly does not go through these checks. An upstream BT guard is necessary but not sufficient. A guard can be too weak, and some paths, such as the trigger path, reach the write node with no guard. When the write node validates, an illegal transition fails closed, whether a guard ran or not. Same-state writes are permitted. A ParticipantStatus snapshot records the current state, and a confirmation such as "still at VFd" is a correct protocol observation, not a transition error.

ECA Details

Preconditions

- A non-None target VFD, RM, or PXA state is passed to the write node

Steps

1. [write_node] Read the participant's current state for the dimension being written (e.g. resolve_participant_state_from_dl) → Current state available
2. [write_node] If target == current, proceed (status confirmation). If is_valid__transition(current, target) is True, proceed. Otherwise return Status.FAILURE with a feedback_message identifying the illegal source→target pair. → Only valid forward transitions or same-state writes reach the DataLayer persist step; invalid jumps return FAILURE.

Postconditions*

- No ParticipantStatus record with an illegal state jump is persisted

BTND-10-006 MUST NOT This codebase MUST NOT persist report-scoped RM state from before a case exists as a ParticipantStatus.

RM state begins at report receipt, and the case may never exist: a receiver may declare a bare report INVALID or CLOSED and never propose a case. That state was held in a standalone ParticipantStatus keyed on (actor, report, rm_state) and used as an existence latch, which gave the type two jobs and therefore made a single writer impossible. The two jobs were also already entangled: _build_owner_initial_status() reused the latch's id as the participant's first ladder rung, and _get_or_create_accepted_status() mutated the stored record in place. VultronReportCaseLink already exists for precisely this window (ADR-0041) and is the report-scoped record, so relocating the state there leaves ParticipantStatus ladder-only — and leaves the writer always holding a case, which is why no further case-absence disposition (ADR-0087) is required.
BTND-10-007 MUST When that validation finds an illegal jump or a backward move, the write node MUST return Status.FAILURE with a descriptive feedback_message. An example illegal jump is vfd → VFD, which skips Vfd.

A failed write must fail closed and say why. The feedback_message names the illegal source and target pair, so a reader can find the bad request without a debugger.
Extends: BTND-10-001
BTND-10-008 MAY On the receive side, a dimension MAY reach the write node with adjacency validation relaxed when the CASE_MANAGER already accepted it under RSH-09 or RSH-06. This includes a non-adjacent forward RM move (RSH-06-006). The write boundary still refuses a backward move.

The CASE_MANAGER admits any forward move that a participant reports (RSH-09). A write node that applied adjacency again would refuse a move that the case already accepted. The forward-only rule still holds at the write boundary.
Supersedes: BTND-10-001
Uses definition from: RSH-06-006
BTND-10-012 MUST This codebase MUST record report-scoped RM state from before a case exists on the report's ReportCaseLink.

RM state begins at report receipt, and the case may never exist. ReportCaseLink is the report-scoped record for that window (ADR-0041). With the state there, ParticipantStatus holds only the case ladder, and its writer always has a case.
Extends: BTND-10-006

Behavior Tree Composability

Requirements for implementing Vultron's behavioral logic as composable, reusable BT structures using the simulator as the canonical blueprint. Covers the workflow of BT composition: how to use the simulator reference, where structures must live, when to use BT composite idioms instead of procedural code, and the fractal composability principle that applies at every depth.

File ID: BTC

Simulator Reference Workflow

ID Priority Requirement Related
BTC-01-001 MUST Before implementing any BT node or subtree in vultron/core/behaviors/, a developer MUST search notes/vultron-bt.txt to locate the corresponding node in the canonical simulation tree.

The canonical tree is the normative definition of Vultron's domain behavior. Implementing without consulting it risks inventing structures that contradict the protocol design.
Implements: BT-06-002
BTC-01-002 MUST After locating a node in notes/vultron-bt.txt, a developer MUST examine the corresponding class in vultron/bt/ to understand the node's children, structure, and composites.

The text tree in notes/vultron-bt.txt is only a rendering. It gives node names, composite symbols and nesting. It does not show what each condition checks or what each action changes. The simulator class holds that logic. A port that does not examine the class can keep the shape of the tree but get its behavior wrong.
Implements: BT-06-002

BT Structure Pre-Definition

ID Priority Requirement Related
BTC-02-001 MUST All BT composite structures used by use cases in vultron/core/use_cases/ MUST be pre-defined as named classes or factory composites in vultron/core/behaviors/ before use.

Business logic lives in core/behaviors/. If use cases construct trees ad-hoc, the business logic migrates into use cases and becomes invisible to analysis of the behavior layer.
Extends: BT-06-001
BTC-02-002 MUST NOT Use cases MUST NOT construct ad-hoc BT composite trees inline. Inline construction means calling py_trees.composites.Sequence(children=[ NodeA(), NodeB(), ...]) or equivalent directly inside a use case's execute() method.

A developer who reads core/behaviors/ cannot see a tree that a use case builds inline in execute(). Nobody can reuse that tree or test it alone. It also moves business logic into the use-case layer, and BTC-02-001 keeps that logic out of this layer.
Refines: BTC-02-001
BTC-02-003 MUST Use cases MUST follow the instantiate-then-invoke pattern when using BTs: (1) import the pre-defined BT class from vultron/core/behaviors/, (2) instantiate it to obtain a root node, (3) wrap it in a py_trees.trees.BehaviourTree, and (4) call tick_once() or equivalent to execute it.

One fixed way to run a tree keeps use cases small and similar. A reader finds the behavior in the named class. The use case only connects the tree to the blackboard and returns its result. Thus no use case gets its own logic to run trees.
Implements: BTC-02-002

BT Idioms Over Procedural Code

ID Priority Requirement Related
BTC-03-001 MUST Behavioral logic that belongs inside a BT MUST be expressed using BT composite idioms (Sequence, Selector/Fallback, Decorator) rather than procedural if/else chains.

BT idioms make logic auditable, extractable, and explainable by anyone who can read the tree structure, without reading implementation code. Procedural logic inside update() is opaque. See also notes/use-case-behavior-trees.md section "The Tree Is the Documentation" for the design invariant that gives this rule its purpose.
Refines: BT-06-001
BTC-03-002 MUST Precondition-then-action logic MUST be modeled as a Sequence where leading children are Condition nodes and trailing children are Action nodes.

In a Sequence of conditions and then actions, each precondition is a visible, named node. A reader sees the guard before the effect. When a guard fails, the tree stops before any action runs.
Refines: BTC-03-001
BTC-03-003 MUST Try-A-or-else-B fallback logic MUST be modeled as a Selector (Fallback) composite with A and B as children.

A Selector shows each alternative as a child, in priority order. Thus the fallback is visible in the tree and in its trace. The same logic in an if/else inside one node hides which branch ran.
Refines: BTC-03-001
BTC-03-004 SHOULD When a leaf node in the canonical simulator BT requires complex implementation logic, that logic SHOULD be expanded into a subtree using BT composite idioms rather than procedural code in a single update() method.

When a leaf hides complex logic in one update() method, the tree structure, the trace and the tests cannot see that behavior. A subtree keeps each step named and visible. This is the reason that BTC-03-001 uses composites, not if/else chains.
Implements: BT-06-004

Fractal Composability

ID Priority Requirement Related
BTC-04-001 MUST The compose-and-reuse principle MUST apply at every depth level of the behavior tree — from single-purpose leaf nodes up to use-case entry trees.

Duplicated logic and hidden logic can occur at all levels of a tree, not only at the top. If the principle applies only to entry trees, the same logic can still be copied between leaves or between mid-level subtrees.
BTC-04-002 MUST When the canonical simulation tree shows the same named behavior appearing at two or more locations, that behavior MUST be implemented as a single reusable class in vultron/core/behaviors/, instantiated separately at each use site.

The simulator reuses a behavior where the protocol has the same meaning in several places. One class keeps those places the same. Thus a fix or a protocol change occurs in one location, not in each copy.
Refines: BTND-02-001
BTC-04-003 MUST A reusable protocol behavior MUST be one BT subtree in core/behaviors/, reused at every call site with no inline duplicate of equivalent logic.

Copies of one protocol behavior drift apart. Then actors act differently on the same event. Extraction at the deepest shared level gives one implementation for each behavior. It does not force large subtrees on call sites that share only a part.
Refines: BTND-02-001
BTC-04-004 SHOULD Every pre-defined BT class in vultron/core/behaviors/ SHOULD be usable both as a standalone use-case entry point AND as a composable child of a larger BT.

A class that runs alone and also as a child can be tested alone. Then it can go into larger trees without a change. Thus no second, parallel version of the behavior is necessary for the composed case.
Refines: BTND-02-002
BTC-04-005 SHOULD An implementer SHOULD extract a shared subtree at the deepest level that more than one call site needs. That level is not the top level by default.

Extraction at the deepest shared level gives one implementation for each behavior. It does not force large subtrees on call sites that share only a part.
Extends: BTC-04-003

Build Workflow Learnings Policy

Defines the content policy for the per-entry incoming learnings queue used by the build and bugfix skills to pass implementation observations upstream to the learn skill. Covers what belongs in the queue, what must not go there, file naming and format, how the learn skill processes and archives entries, and the learning history entry type. The queue is narrow by design: findings with a definite owner are routed to a GitHub issue or an in-session fix at the moment of discovery, and only unverified general claims and spec divergences are queued for batch processing (BW-07).

File ID: BW

Incoming Learnings File Format

ID Priority Requirement Related
BW-02-006 MUST The learnings-index entry point MUST render one line per file in plan/incoming/learnings/ that carries its source, title and filename.

orient-agent needs a map of the queue, not its full text. If it reads each full file, it uses much of the orientation budget. Each title states its lesson, so one line for each file gives orientation what it needs.
Uses definition from: BW-02-001
BW-02-007 MUST When a file fails validation, the learnings-index entry point MUST still print the valid entries and report each failure on stderr.

People write the queue by hand, so a malformed file is probable. If one bad file stops the index, orientation cannot see the other entries.
Extends: BW-02-006

learning History Entry Type

ID Priority Requirement Related
BW-04-001 MUST The learning entry type MUST exist in HistoryEntryType in vultron/metadata/history/types.py.

The archiver accepts only types in HistoryEntryType (HM-02-002). Thus archived learnings need their own member, so that the archiver can write and index them.
Refines: HM-02-002
BW-04-002 MUST History entries of type learning MUST follow the same frontmatter and body format as all other append-history entry types, including required fields title, type, timestamp, and source.

Indexes and show-history read all entries in the same way. A learning with a different format would break those readers, or need special handling.
Refines: HM-02-001

append-history --from-file Behaviour

ID Priority Requirement Related
BW-05-001 MUST uv run append-history --from-file <path> MUST write the file's frontmatter and body through the normal write path to plan/history/YYMM/<type>/<source>.md. It takes type, title, source and timestamp from the frontmatter.

Incoming learnings already have complete frontmatter. Thus the archive step can read it from the file, and the caller does not have to state it again.
BW-05-004 MUST uv run append-history --from-file <path> MUST delete the source file after a successful write.

The tool deletes the source after the write, so each learning is in one location only: the queue or the archive. A copy left in the queue would be processed again.
Extends: BW-05-001
BW-05-002 MUST uv run append-history --from-file MUST be mutually exclusive with the positional type argument and the --title, --source, --file and --timestamp flags.

With --from-file, the frontmatter in the file is the only source of the entry's metadata. If a flag conflicts with it, nobody can tell which value applies.
BW-05-005 MUST When an agent combines --from-file with a conflicting argument, uv run append-history MUST exit non-zero with an error message that names the conflicting flags.

A refusal with no message does not tell the agent what to change. The message names the flags, so the agent can remove them and run the command again.
Extends: BW-05-002
BW-05-003 MUST uv run append-history --from-file MUST reject files whose frontmatter timestamp is more than 60 seconds in the future (HM-06-004).

--from-file must not bypass the validation that all other entries get. The same future-date check applies, so a file that the normal path rejects cannot go into the archive by this path.
Derives from: HM-06-004
BW-05-006 MUST uv run append-history --from-file MUST reject files with missing or invalid frontmatter fields (HM-02-001).

--from-file must not bypass the frontmatter validation that all other entries get. An archived entry with a missing or invalid field breaks the indexes and show-history, which read every entry in the same way.
Uses definition from: HM-02-001

Case Bootstrap Trust

Requirements for establishing trust in a VulnerabilityCase and its CASE_MANAGER at non-owner sites. Governs the bootstrap process by which a non-owner participant verifies that an incoming case and its managing actor are legitimate before accepting case state updates.

File ID: CBT

Out-of-Order Handling

ID Priority Requirement Related
CBT-03-005 MUST This codebase's pre-bootstrap queue (CBT-03-001, CBT-03-003) MUST expire after 300 seconds by default, configurable via AppConfig.pre_bootstrap_queue_timeout_seconds (environment variable VULTRON_PRE_BOOTSTRAP_QUEUE_TIMEOUT_SECONDS).

A queue with no expiry holds activities for a case that never bootstraps for as long as the process runs. A fixed default gives every deployment the same bound, and the override lets an operator fit it to how slow its peers are.
Implements: CBT-03-001
See also: CBT-03-003 — the default timeout value is not how the drop is done
CBT-03-006 MUST When this codebase drops an expired pre-bootstrap queue (CBT-03-003), it MUST log a warning.

An expired queue drops activities the actor received but never processed. Without a log record, an operator cannot tell that a case missed its bootstrap or which activities were lost.
Extends: CBT-03-003
CBT-03-007 MUST This codebase MUST treat a case's pre-bootstrap queue interval (CBT-03-001) as expired once the arrival stamp of the first message queued for the case, plus the interval, is not after the instant of the act that judges it: a later delivery naming the case or the bootstrap that releases its messages, at its arrival stamp, or a sweep, at its own instant.

Each received act is judged at its arrival stamp (CS-13-010), so a bootstrap that arrived inside the window releases the queue even when a backlog delayed its processing past the window. A released message is not judged again at its replay: it runs at its own arrival stamp, which is inside the window the release found open.
Refines: CBT-03-003
See also: CBT-03-001 — names the interval this measures; CBT-03-003 is the rule it refines

Verification

ID Priority Requirement Related
CBT-05-001 MUST Tests MUST verify that the original report submitter accepts CASE_MANAGER-originated Announce(VulnerabilityCase) updates only after a valid bootstrap Create(VulnerabilityCase) from the report receiver has established trust.

This order keeps an actor the submitter never checked out of its replica. Messages usually arrive in order, so a regression that accepted an Announce before the bootstrap would show no error in a normal run. A test must check it.
CBT-05-002 MUST Tests MUST verify that a bootstrap Create(VulnerabilityCase) is rejected when the sender does not match the actor that received the report or when the case does not reference the known submitted report.

These two checks make the bootstrap a Trust Anchor (CBT-01-005). If either check stops working, any actor can seed a case at the submitter, and a normal run, where every sender is honest, shows no error.
CBT-05-003 MUST Tests MUST verify that pre-bootstrap CASE_MANAGER messages remain unapplied and expire safely (CBT-03-003, CBT-03-006).

A message arrives before its bootstrap only when delivery is out of order, which a normal run seldom causes. Only a test checks regularly that such a message stays unapplied and that its expiry follows CBT-03-003 and CBT-03-006. The receiver asks no one to resend what it dropped: the CASE_MANAGER recovers a dropped Invite once the participant states its position (SYNC-17-008, ADR-0163).
Verifies: CBT-03-003
Verifies: CBT-03-006
CBT-05-004 MUST Tests MUST verify that late joiners establish trust through InviteActorToCase and may then accept CASE_MANAGER-originated Announce(VulnerabilityCase) updates without an intermediate Create(VulnerabilityCase) bootstrap.

A late joiner gets its Trust Anchor from a different message than the submitter does. A test of the submitter's bootstrap does not show a break in the joiner's.
CBT-05-005 MUST Tests MUST verify that a valid bootstrap Create(VulnerabilityCase) causes the reporter's participant status record to be stored as an embedded participant in the new case, making the reporter addressable without a separate InviteActorToCase.

If the bootstrap does not store the reporter's participant record, the reporter is not a participant in its own replica, and it would need an Invite to join the case it reported.
CBT-05-006 MUST Tests MUST verify that AddParticipantStatusBT executes successfully on the reporter's replica after bootstrap, confirming the reporter appears in the CASE_MANAGER's participant index.

The reporter's later status updates find its participant record through the replica's participant index. If the bootstrap leaves the reporter out of that index, its first status update fails.
CBT-05-007 MUST Tests MUST verify that the bootstrap stores the reporter's participant record at RM.ACCEPTED (CBT-01-008).

RM.ACCEPTED is the only RM state a reporter can be in when it reports (CBT-01-008). If the bootstrap stored another state, the reporter's later RM transitions would start from the wrong state, and a normal run would show no error.
Verifies: CBT-01-008

Case Event History

Requirements for a read-only analysis layer that reads a case ledger and emits the case's event history: one record per Coordinated Vulnerability Disclosure event, labeled by the participant it belongs to and by the ledger entry that caused it, carrying the log index and both clocks. Covers the package and its command, which ledger copy it reads, the fields of one event record, how each event is derived, the per-participant case-state sequences it projects, the data-gap labels it carries, and test requirements. The measures computed from the history are research material and are not specified here. Each verification: field states the criterion a test must meet; the implementation names the test that meets it.

File ID: CEH

Package and Invocation

ID Priority Requirement Related
CEH-01-001 MUST NOT A module in the protocol path MUST NOT import the event-history layer.

The layer reads a finished case and computes nothing the protocol acts on. A one-way boundary keeps an analysis change from reaching case behavior, and keeps the research code out of the import graph that the architecture boundary tests govern. Which package holds the layer is a layout choice and lives in notes/case-event-history.md, not here.
CEH-01-002 MUST NOT The event-history layer MUST NOT write to the DataLayer, to a case ledger, or to any store.

A measurement pass that wrote to a case could change the thing it measures, and a reader given write access to a ledger can break the hash chain. Read-only access makes the layer safe to run on an archived ledger.
Extends: CEH-01-001
CEH-01-003 MUST The layer MUST expose a Python function that takes a ledger source and returns the case event history.

The baseline work and the timing metrics are Python that consumes the history directly. A library entry point lets them import it without a subprocess, and keeps the command a thin wrapper over the same code the tests exercise.
CEH-01-004 MUST The layer MUST provide a console script that reads one case's ledger and writes its event history.

A researcher reads one case by hand before trusting a measure computed over many. A command makes each committed demo recording inspectable without writing Python.
CEH-01-005 MUST The console script MUST offer a machine-readable output format and a human-readable table format.

The two formats serve different readers. A later tool consumes the machine-readable form, and a person checking a case against its scenario narrative reads the table.
Extends: CEH-01-004
CEH-01-006 MUST The human-readable table MUST render an event's actor and object by their friendly display names, never by a bare URI.

Two tools that read the same ledger and name the same actor differently are hard to read side by side. One display-name resolver, serving both, keeps one answer for one actor.
Depends on: DRPT-03-003
CEH-01-007 MUST NOT The layer MUST NOT keep its own table of event phrases parallel to SEMANTIC_REGISTRY.

A second phrase table drifts as the set of semantic types grows, and the drift is invisible until a reader sees a stale phrase. The registry is the one source.
Refines: DRPT-03-005
CEH-01-008 MUST The console script MUST exit non-zero when its input is missing, holds no ledger entry, or names a case the input does not contain.

A tool that reports an empty history on a bad path looks like a case with no events. A non-zero exit tells a caller and a test apart from a real empty result.
Extends: CEH-01-004

Ledger Input Selection

ID Priority Requirement Related
CEH-02-001 MUST The layer MUST read its entries from case-ledger JSONL files.

A file is readable offline, so a measure runs against an archived ledger, a committed demo recording, or a ledger from another deployment. A DataLayer read would need a live store and could not reach any of those.
CEH-02-002 MUST The layer MUST read a dimension state wherever a payload snapshot spells it, across every depth and spelling the ledger format admits.

A dimension state sits at several depths and in several spellings in a payload snapshot. A reader that misses one of them reports no state for every affected entry, which a measure cannot tell apart from a state the case never reached. Which module holds that reader, and which tools share it, is a layout choice and lives in notes/case-event-history.md.
Depends on: DRPT-02-003
CEH-02-003 MUST The layer MUST take the ledger files it reads from its caller.

The committed recordings are named case-actor.jsonl under a scenario directory, while a demo run writes <actor>-case-ledger.jsonl under an actor directory. A layer that chose for itself would have to pick one shape, and a test corpus it cannot open is a test that never runs.
CEH-02-010 MUST NOT The layer MUST NOT depend on a file-naming or directory-naming convention to find its ledger files.

Either naming shape is one deployment's habit, not a property of the format. A layer that globbed for one would report an empty history for the other, which a caller cannot tell from a case with no events.
Refines: CEH-02-003
CEH-02-009 MUST The layer MUST identify the CASE_MANAGER's copy of a ledger from the entries themselves, never from the file's name or its directory's name.

A ledger file is named for neither its actor nor its role, so a path-derived answer finds no CASE_MANAGER and sends every recording down the merge path. No entry names a copy's holder either: a replica's entries are byte-identical to the CASE_MANAGER's. So the copy is identified by completeness, which is known only relative to the input, and the layer reports separately whether the entries confirm the ledger's end.
Extends: CEH-02-004
CEH-02-004 MUST When the input holds the CASE_MANAGER's own copy of a case ledger, the layer MUST derive that case's event history from that copy alone.

Only the CASE_MANAGER's ledger is complete. A participant's replica stops receiving entries while its embargo consent has lapsed and after its report closes, so an event recorded in a gap it missed is absent from its copy.
CEH-02-005 MUST With no CASE_MANAGER copy of a case ledger, the layer MUST merge the participant replicas and de-duplicate the entries by entry hash.

Several partial replicas together often cover the whole ledger. Merging recovers the entries that any one replica missed, and the entry hash identifies the same entry in two copies.
Extends: CEH-02-004
CEH-02-006 MUST A case event history built from merged replicas MUST record that it was merged, and name the log indices that no replica supplied.

A merged history can still have holes, and a measure over a history with a hole is wrong rather than imprecise. Naming the missing indices lets a caller refuse the history instead of scoring it.
Extends: CEH-02-005
CEH-02-007 MUST The layer MUST group its entries by case identifier and derive one event history for each case.

The log index restarts at zero for each case, and one input directory can hold the ledgers of several cases. A history that interleaved two cases would order their entries by a key that is not unique across them.
Depends on: DRPT-02-006
CEH-02-008 MUST The layer MUST degrade one malformed JSONL row to one unusable entry, and finish the rest of the history.

One bad row in a long ledger is worth reporting, not worth losing every other event to. Aborting the pass on it also hides which row was bad.
Depends on: DRPT-02-003

The Event Record

ID Priority Requirement Related
CEH-03-001 MUST The layer MUST refuse an event record that is missing a required field, at construction.

The record crosses from this layer to every measure built on it, so a missing field must fail where it is built rather than read as an absent event by each caller in turn. Which validation library enforces it is a code-style matter settled project-wide by CS-17-001.
Depends on: CS-17-001
CEH-03-002 MUST An event record MUST carry the kind of event it reports, drawn from a closed enumeration.

A measure selects events by kind, and a free string lets two spellings of one kind both pass. A closed enumeration makes an unhandled kind a load-time error.
CEH-03-003 MUST An event record for an event that belongs to one participant MUST name that participant.

Report management, the vendor fix path, deployment and embargo consent are per-participant, so vendor awareness and fix readiness occur once for each vendor. An unlabeled event cannot be assigned to the vendor it describes.
CEH-03-004 MUST An event record for an event that belongs to the case MUST record that it belongs to the case rather than naming a participant.

Public awareness, a public exploit, observed attacks, and the start and end of the embargo happen at most once for the whole case. Attributing one to the participant whose entry carried it would count it once per participant.
Extends: CEH-03-003
CEH-03-005 MUST An event record MUST carry the log index of the ledger entry it was derived from.

The log index is the authoritative order in which the CASE_MANAGER admitted the changes, and the only order a measure may treat as causal. A timestamp order is supporting evidence.
Depends on: CLP-14-001
CEH-03-006 MUST An event record MUST carry the commit stamp of its ledger entry.

Every commit stamp in a case comes from the CASE_MANAGER's one clock, so an interval between two of them is a valid comparison. It is the default clock for a measure that spans two senders.
Depends on: CLP-14-002
CEH-03-007 MUST An event record MUST carry, in its own field, the claimed time of the activity in its ledger entry whenever that entry states one.

The claimed time comes from the sender's clock and should be when the event occurred. An interval whose two ends come from one sender is better measured on it, because a fixed offset in that sender's clock cancels out. The field is nonetheless absent-able: CLP-15-008 refuses an inbound activity carrying no published, but this layer is handed archived and foreign ledgers it never validated, and an absent claimed time must read as absent.
Depends on: CLP-15-006
CEH-03-008 MUST NOT The layer MUST NOT substitute one of the two times for the other, nor combine them into a single time.

The two times answer different questions and come from different clocks. A reader that cannot tell which clock a value came from cannot judge whether an interval is valid.
Refines: CEH-03-007
CEH-03-009 MUST An event record MUST name the semantic type of the ledger entry that caused it.

Several different protocol acts produce the same state change, and which act did it is part of what a process measure reports. Naming the semantic type also lets a reader trace an event back to its entry.
CEH-03-010 MUST An event record MUST carry every data-gap label that applies to it, from a closed enumeration of the gaps that affect an event's time.

A measure built on an event inherits that event's gap. Carrying the label on the record lets a measure state its own limits instead of each measure rediscovering the gap.
CEH-03-011 MUST The layer MUST label an event seated by the case-creation sequence as stamped at creation rather than at the event.

The creation sequence puts the Case Owner at report received and the reporter at report accepted, and the CASE_MANAGER commits both during creation. So the commit stamp of each is the creation time, not the time of the event.
Implements: CEH-03-010
CEH-03-012 MUST The layer MUST label a case-level public awareness, public exploit or observed attacks event as stamped when the CASE_MANAGER adopted it.

The case's public state changes only when the CASE_MANAGER commits its own case status. Both times on that entry come from the CASE_MANAGER's clock at adoption, so neither is when a participant first reported the event.
Implements: CEH-03-010
CEH-03-013 MUST The layer MUST label every end-time embargo exit the CASE_MANAGER commits, and every timed-out invitation, as stamped when the CASE_MANAGER next acted.

The label means the stamp may lag the deadline that caused the change. The CASE_MANAGER's lazy check makes the change when it next handles the case, so the stamp can be much later than the deadline. EMB-13-003 also admits an outside request at the end time, such as from a Sentinel watching embargo timers, but the ledger records both paths as the same Remove(EmbargoEvent) with no requester, so the label cannot tell them apart. The deadline the event carries (CEH-03-015) gives the true end time.
Implements: CEH-03-010
Depends on: EMB-13-003
CEH-03-014 MUST The layer MUST label a public exploit or observed attacks event as reported out of band.

Both happen outside the protocol, and the case learns of either only when a participant reports it. The record does not show how long that took, so no measure on these events can bound the delay.
Implements: CEH-03-010
CEH-03-015 MUST When any entry in the ledger states a deadline that bounds an event's real time, the event record MUST carry that deadline.

An embargo that ended because its end time passed really ended then, and the commit stamp is only the latest possible end. The deadline is the better value, and it is not always on the entry recording the event. A timed-out invitation carries no RSVP deadline of its own: CM-28-013 lets only an INVITED consent row hold one, and the row has already moved to TIMED_OUT. The layer must carry that deadline forward from the earlier invitation entry.
Extends: CEH-03-013

Event Derivation

ID Priority Requirement Related
CEH-04-001 MUST The layer MUST derive a report-management, fix-path, deployment or public state event by comparing an entry's state against the state already reached.

Several different protocol acts move the same state machine, and joining a case, answering a full-case invitation and leaving a case all change report management. A table keyed on the semantic type alone would miss whichever act it omitted.
CEH-04-002 MUST The layer MUST emit one event for each state a participant's report management enters.

Report management has seven states, START among them, and the measures of intake and triage need the time of each one a participant actually enters. Emitting only the four states that have a symbol in the research pages would drop the deferred and invalid verdicts.
Implements: CEH-04-001
CEH-04-003 MUST The layer MUST emit a vendor-awareness event and a fix-readiness event separately, for each participant that holds the Vendor role.

The interval between the two is a vendor's time to fix, the measure that service level expectations most often limit. A case with ten vendors has ten of each event.
Implements: CEH-04-001
CEH-04-004 MUST The layer MUST emit a fix-deployed event for each participant that holds the Deployer role and reaches a deployed state.

Only a participant with the Deployer role holds a deployment state. A deployer that is not also a vendor may deploy after any vendor in the case has a fix ready, so the case does not say whose fix it deployed.
Implements: CEH-04-001
CEH-04-005 MUST The layer MUST derive the embargo start, the embargo exit and a consent answer from an entry's semantic type and its carried object.

None of the three is a dimension of a participant status, so state comparison cannot find them. The embargo register entries and the consent rows carry no time of their own, so only the entry that recorded a step holds its time.
CEH-04-006 MUST An embargo exit event MUST carry whether the embargo reached its end time or ended early.

The two ways an embargo ends mean different things about the case. An embargo that ran to its end time ended on its own terms, and one that ended early ended with time left that a measure can report as the cost.
Extends: CEH-04-005
CEH-04-007 MUST When an embargo exit records a structured cause, the embargo exit event MUST carry that cause as recorded.

An early exit caused by a threat signal says something different about the case from one caused by every fix being ready. Only an early termination carries a cause, and a replica never works one out from its own state.
Extends: CEH-04-006
CEH-04-008 MUST The layer MUST emit a distinct event for a participant agreeing to an embargo, declining it, and letting its invitation time out.

Inaction is recorded as a time-out and never as an explicit refusal, and the rate of those time-outs is a measure of its own. Collapsing the three answers would make an unanswered invitation indistinguishable from a refusal.
Extends: CEH-04-005
CEH-04-009 MUST A participant's embargo consent event MUST name the embargo register entry it answers.

A case can hold several proposed embargoes at once, and a participant keeps one consent row for every entry in the register. An answer that did not name its entry could not be matched to the embargo it was about.
Extends: CEH-04-008
CEH-04-010 MUST The layer MUST emit a joining event for each participant that accepted its invitation, derived from the entry recording that acceptance.

Time to join is measured from an invitation to this event, and the entry that first records a participant is not it. CM-11-006 has the CASE_MANAGER create the invitee's record at RM.RECEIVED while it is still inert, and CM-11-001 leaves report management there when the stub invitation is accepted, so joining moves no state. Keying on the acceptance entry also keeps a joining event off a participant that never joined: a refused or expired invitation leaves that inert record untouched.
Implements: CEH-04-005
Depends on: CM-11-001
CEH-04-011 MUST The layer MUST order the events of one case by the log index of the entry each was derived from.

The log index is the authoritative causal order. Ordering by either timestamp instead would reorder the entries whose claimed times came from two clocks.
Depends on: CLP-14-001
CEH-04-012 MUST When one ledger entry records more than one event, the layer MUST emit every one of those events, in the order the entry records them.

The creation sequence seats one participant record at several report-management states in a single entry: in the committed recordings the genesis entry puts the CASE_MANAGER's own participant at received, valid and accepted together. Emitting one event per entry would drop all but the first. A case closure is not a second example and must not be read as one. CM-23-022 commits one entry per transition, so a leave from valid gives two entries rather than one entry holding two events.
Extends: CEH-04-011
CEH-04-013 MUST NOT The layer MUST NOT emit an event for a ledger entry that records no change to a state the event enumeration covers.

The ledger records every change to the case file, including notes, ownership and recommendations, and most of those are not events the measures use. An event for each entry would make the history a copy of the ledger.
Refines: CEH-04-001
CEH-04-014 MUST NOT The layer MUST NOT derive a participant's event from a status an entry carries as a recommendation or an offer.

An entry recommending an actor for a case carries a whole participant object for an actor that is not yet in the case, at RM.START. In the committed recordings that object appears several entries before the actor's real record, so a layer that read every participant-shaped object would date the actor's first event to before it was invited, and would give a recommendation a vendor-awareness slot.
Refines: CEH-04-001
CEH-04-015 MUST NOT The layer MUST NOT emit an event for a state that sits behind the state already reached.

CEH-04-013 excludes only an entry that records no change, and a snapshot naming an earlier state is a change. Emitting it would put a backward step into a history the state machines forbid, so a measure would read a regression the case never had.
Extends: CEH-04-013
CEH-04-016 MUST The layer MUST report each entry it excluded for naming a state behind the state already reached.

Dropping such an entry silently would hide a real disagreement between two copies of a case, which is a finding in its own right. Surfacing it beside the events lets a caller judge the history, as CEH-02-006 does for a merge hole.
Extends: CEH-04-015
CEH-04-017 MUST The layer MUST emit an invitation event each time a participant's consent row for an embargo register entry becomes INVITED with an RSVP deadline, carrying that deadline.

A measure of Invites answered before their deadline counts Invites, not rows at their last status: a row invited again after a timeout holds two Invites (CM-18-003, EMB-17-003), and only the invitation shows which answer ends which Invite. The first stub Invite records no RSVP deadline on the invitee's row, so it is no invitation event; a stub Invite re-issued after the embargo changed records one on the row for the embargo now in force (CM-11-016), so it is one.
Extends: CEH-04-008
CEH-04-018 MUST The layer MUST emit one case-closed event for the case, derived from the Case Owner's Leave(VulnerabilityCase) entry.

The owner's Leave closes the case (CM-23-002), and the CASE_MANAGER then times out every Invite still awaiting a reply without waiting for its deadline (CM-23-014). A measure has to tell those timeouts from a pocket veto, and has to know whether the case is still open, so it needs the close's log index and commit stamp. Any other participant's Leave closes only its own report, which its status entries already record.
Depends on: CM-23-002

Per-Participant Case-State Sequences

ID Priority Requirement Related
CEH-05-001 MUST The layer MUST project, for each participant whose events include a vendor-awareness event, that participant's case-state events as an ordered sequence.

The case-state history rules admit only the four vendor-fix-path states vfd, Vfd, VFd and VFD, so a sequence must open on vendor awareness to replay at all. A participant holding the Deployer role but not the Vendor role has no vendor-fix-path state of its own (CSB-15-004) and so cannot open one; keying the projection on the event rather than on the role is what keeps an unreplayable sequence from being built in the first place. CEH-05-007 says what that participant gets instead.
CEH-05-002 MUST A projected sequence MUST hold only the six case-state events, in the vocabulary the case-state history validator reads.

The validator replays a sequence from the initial state and accepts it only if every step is a valid transition. A sequence carrying report or embargo events would not replay.
Extends: CEH-05-001
CEH-05-003 MUST A projected sequence MUST combine the participant's own vendor-fix-path and deployment events with the case's public state events.

The case state is the compound of a participant's fix path and the case's public state. A sequence holding only one of the two would be a partial history that replays to the wrong state. A participant holding the Vendor role but not the Deployer role contributes no deployment event, which leaves its sequence at VFd and is a valid incomplete prefix under CEH-05-005.
Refines: CEH-05-002
CEH-05-004 MUST Every projected sequence MUST be a valid case-state history prefix.

Checking the prefix turns a derivation bug, or an entry a CASE_MANAGER would refuse, into a reported refusal instead of a wrong score. The CASE_MANAGER does not catch every such compound: it validates a participant's dimensions and the case's public state separately and skips a rule reading a dimension the participant lacks (ADR-0075). This layer builds the compound, so it owns the check.
Depends on: CSB-17-005
CEH-05-005 MUST The layer MUST treat a projected sequence that is missing a trailing event as an incomplete prefix, not as an invalid history.

Many cases never see a public exploit or observed attacks, and an open case has not closed, so a sequence that stops early is normal. Only a trailing event may be missing. The ephemeral rules (CSB-17-003) oblige a specific next event, so a public-state event with no vendor awareness in front of it is refused. An event a transient state forces is not missing: CEH-05-009 places it.
Depends on: CSB-17-010
CEH-05-006 MUST NOT The layer MUST NOT combine the sequences of several vendors into one sequence for the case.

Vendor awareness and fix readiness occur once for each vendor, and no rule yet says which vendor's event stands for the case. A rule chosen here would decide an open research question without review.
Refines: CEH-05-001
CEH-05-007 MUST For a participant the layer projects no sequence for, the layer MUST report that participant as unprojectable with a stated reason.

A participant holding the Deployer role but not the Vendor role has case-state events and no sequence they can replay in. Silence or an empty list reads as a participant with no events, which is a different and wrong answer. Its events stay in the event history, where a measure needing no replayable sequence reads them.
Extends: CEH-05-001
CEH-05-008 MUST NOT The layer MUST NOT score a projected sequence.

The existing desiderata scorer admits only a complete six-event history and raises on anything shorter, while CEH-05-005 makes an incomplete sequence the normal result, so there is no score this layer could compute for a typical case. An incomplete sequence is scored through its valid completions by a separate measure that reads the sequence (ADR-0182), and the measures computed from a history are out of this topic's scope in any case. The layer's deliverable is the validated sequence.
Refines: CEH-05-004
CEH-05-009 MUST The layer MUST follow each transient state with the event it forces, and mark that event. When the next recorded event is another, the layer moves the forced event up if the ledger records it later, and implies it otherwise.

pX forces P and vP forces V (CSB-17-003): a published exploit makes the public aware at once, and an aware public makes the vendor aware at once. So recorded P, X, V is P, V, X; X, V, P is X, P, V; and V, X, A is V, X, P, A. An implied event carries the forcing event's log index and clocks. The marks keep the real order visible; the history is unchanged. Decided by the project owner on PR #6283.
Refines: CEH-05-004

Testing

ID Priority Requirement Related
CEH-06-001 MUST Unit tests MUST derive an event history from each committed canonical demo ledger recording and assert the events that the scenario's narrative requires.

The recordings are the CASE_MANAGER's own copies of real runs, committed and covering an embargo termination, an embargo revision, a refused invitation and several vendors. They give known histories to check a derivation against.
CEH-06-002 MUST Unit tests MUST assert that every sequence projected from a committed recording is a valid case-state history prefix.

A derivation that mislabels an event usually produces a sequence that cannot replay. Checking every recording turns that class of bug into a test failure rather than a wrong measure.
Extends: CEH-06-001
CEH-06-003 MUST Unit tests MUST cover the merge path with a fixture whose replicas are each partial and together incomplete, and assert the reported missing log indices.

The merge path runs only when the CASE_MANAGER's copy is absent, so no recording exercises it. A fixture with a hole is the only way to check that the hole is reported rather than scored.
Depends on: CEH-02-006
CEH-06-006 MUST Hand-built ledger fixtures MUST cover an end-time embargo exit, a declined invitation, a timed-out invitation, and a Vendor-less Deployer.

No committed recording holds any of the four. Every recording's embargo ends early with a termination cause, every consent row is agreed, invited or uninvited, and the one recording with a deployer gives that actor the Vendor role too. Without fixtures, the requirements on end-time exits, on the three consent answers and on an unprojectable participant pass with nothing exercising them, which is how a derivation bug survives a green suite.
Extends: CEH-06-001
CEH-06-004 MUST A command-line smoke test MUST run the console script against one recording and assert its exit code and its written output.

The library tests never call the entry point, so a broken argument or a missing script registration passes them. A smoke test fails on either.
Depends on: CEH-01-004
CEH-06-005 MUST Unit tests MUST assert that one event of each data-gap kind carries its label.

A label that is defined but never attached reads to a caller as "no gap here", which is worse than no label at all. The four kinds are an event seated at case creation, one stamped at adoption, one a passing deadline caused, and one reported out of band. One test per kind keeps each attachment honest.
Depends on: CEH-03-010

Case Ledger Processing

Requirements for participant assertions, CASE_MANAGER canonicalization, local case audit ledgering, recorded-history projection, and replication-facing CaseLedgerEntry objects. Covers the commit authorization model, per-case genesis hash derivation, the canonical entry criteria that separate the case ledger from the process log, the CASE_MANAGER inbox routing path that enables ledger entry authorship, and the causal-ordering model that makes log_index order the authoritative causal sequence.

File ID: CLP

Canonical CaseLedgerEntry

ID Priority Requirement Related
CLP-02-010 SHOULD In single-node deployments, the term field of a CaseLedgerEntry SHOULD be omitted or set to null.

A single-node deployment has no Raft cluster; populating term in that context adds noise without meaning.
CLP-02-011 MUST In multi-node CASE_MANAGER cluster deployments, the term field of a CaseLedgerEntry MUST be populated with the current Raft term at time of append.

The Raft term anchors each ledger entry to the leader epoch in which it was written, enabling followers to detect stale leader writes during leader-change scenarios.
CLP-02-015 MUST This codebase's CaseLedgerEntry and HashChainLedgerRecord MUST name their semantic-type field semantic_type (CLP-02-014).

Received events carry the same value as VultronEvent.semantic_type, so one name serves both sides.
Implements: CLP-02-014

Canonical Ledger and Replication

ID Priority Requirement Related
CLP-04-008 MUST This codebase MUST surface through structured logging each refusal (CLP-04-007), including a received CaseLedgerEntry whose hash its content does not reproduce (SYNC-03-006) and a case copy that conflicts with the replica's chain (SYNC-16-006), both at ERROR, and each received processing fault reporting a failure to apply a CaseLedgerEntry (SYNC-16-002). Its freshness-gate and tail-reconstruction helpers (is_ledger_fresh_for_case, reconstruct_tail_hash) read the ledger directly and apply no disposition filter.

A refusal leaves no ledger entry (CLP-04-007), so the log is the only record that it happened. A hash refusal or a conflicting case copy means a replica and the CASE_MANAGER disagree, which needs an operator, so it is logged at ERROR. The freshness and tail helpers must read the ledger as stored, because a filter there could hide an entry the chain depends on.
Uses definition from: SYNC-03-006
Uses definition from: SYNC-16-002
Uses definition from: SYNC-16-006
See also: CLP-04-007 — logging a refusal is not how refusals are kept off the ledger

Pending Assertion Suppression

ID Priority Requirement Related
CLP-06-002 MUST NOT This codebase MUST NOT treat pending assertion state as canonical case history, such as by reading it to reconstruct participant membership or case state.

A pending assertion is only the participant's guess about what the CASE_MANAGER will admit. The CASE_MANAGER can refuse it. If a replica reads its own pending records as history, it shows a change that the ledger may never record.
CLP-06-003 MUST Implementations that provide pending assertion suppression MUST make its timeout configurable.

The time for an entry to come back depends on the deployment and the network. A fixed value is too short for some deployments and too long for others. A default gives a working start, and the setting lets an operator tune it.
CLP-06-007 SHOULD The default timeout of pending assertion suppression SHOULD be 180 seconds.

A default gives a working start. 180 seconds covers an entry's usual round trip with room to spare, so a normal delay does not time out.
Extends: CLP-06-003
CLP-06-004 MUST When a pending assertion reaches its timeout without a matching canonical confirmation, this codebase MUST move it to a timed-out state.

An assertion that gets no entry and no refusal notice is a fault that someone must look at. If it stays pending, it stops later sends with no visible reason. The timed-out state releases it, and the error log shows the operator that something failed.
CLP-06-008 MUST When a pending assertion times out without a matching canonical confirmation, this codebase MUST log the timeout at ERROR.

An assertion that gets no entry and no refusal notice is a fault that someone must look at. The error log shows the operator that something failed.
Extends: CLP-06-004
CLP-06-005 MUST NOT Pending assertion timeout handling MUST NOT send an assertion again itself; only a later behavior evaluation decides whether to send it.

An automatic retry can send an assertion that the participant does not want at that time, or that is wrong for the case at that time. The behavior tree knows the current state and decides again. A timer does not know the current state.
CLP-06-006 MUST A pending assertion entry MUST be cleared when a matching canonical CaseLedgerEntry is observed, or when the CASE_MANAGER's refusal notice for the assertion arrives (CLP-05-001)

A pending record that stays after the answer arrives stops the participant from sending a correct new assertion. Both the entry and the refusal notice end the wait, so both must clear the record.
Uses definition from: CLP-05-001

Canonical Entry Criteria and Ledger/Process-Log Separation

ID Priority Requirement Related
CLP-07-016 MUST This codebase MUST run an act's commits and every later node of the act's tree in one DataLayer transaction (CLP-07-015). For a received act, the guarded commit of the received activity runs in the same transaction as the consequences the act's tree commits after it.

One transaction is the default of every received tree that commits to a case, and a tree does not need to ask for it. A new tree therefore cannot lose it by accident.
Implements: CLP-07-015
CLP-07-024 MAY A received tree MAY commit outside the act's transaction (CLP-07-016) only when it names a registered, reasoned exemption.

A named exemption makes each tree that commits outside the transaction a recorded decision with a reason, which the architecture test pins.
Supersedes: CLP-07-016
CLP-07-025 MUST For an embargo act, this codebase MUST trial-apply every entry before the act's first commit (CLP-07-023).

A trial apply before the first commit finds an embargo entry that will not apply while nothing is written yet.
Implements: CLP-07-023
CLP-07-005 SHOULD The CASE_MANAGER commit boundary SHOULD enforce CLP-07-001 through CLP-07-004 with a runtime guard that rejects non-canonical entries before they enter the hash chain, failing fast rather than silently polluting replicated history

A guard at the commit boundary stops a non-canonical entry before it enters the hash chain. After that point every replica holds the entry and no fix can remove it. The guard's signature set must list every activity a CASE_MANAGER legitimately ledgers, such as Offer(CaseParticipantRole) (ADR-0039). A missing signature makes the guard refuse a valid assertion.
Implements: CLP-07-001
Implements: CLP-07-004
Implements: CLP-07-002
Implements: CLP-07-003
CLP-07-009 MUST A payloadSnapshot MUST be in the wire (AS2) shape, so that the wire vocabulary class for its type_ can revalidate it without translation. So must every object carried inline in one (CLP-07-006). A received activity's snapshot is the received body itself (CLP-07-011). It is already in the wire shape, and nothing renders it.

The snapshot is the replication content, and receivers must rebuild it (CLP-01-003, CLP-01-004, CLP-07-011). A core object that is dumped directly gives core field names or the wrong structure, which a receiver cannot read. The rendering port is the one place that produces the wire shape, so every type is rendered the same way.
Derives from: CLP-07-011
See also: CLP-07-006 — context for the reader
CLP-07-020 MUST When this codebase captures a core domain object in a payloadSnapshot, it MUST produce the wire shape through the core→wire rendering port (ARCH-20-001). It never dumps the core object with by_alias=True or rewrites dumped keys in core.

A core object that is dumped directly gives core field names or the wrong structure, which a receiver cannot read. The rendering port is the one place that produces the wire shape, so every type is rendered the same way.
Implements: CLP-07-009
Refines: ARCH-20-001
CLP-07-010 MUST NOT Core snapshot-construction code MUST NOT special-case individual field names to reach the wire spelling (e.g. moving a nested rm.state to a flat rmState). Structural differences between the core and wire shapes are the responsibility of the rendering port (ARCH-20-001).

A per-field patch in core is a partial reimplementation of the translator that drifts as either shape evolves, and it is invisible to the adapter layer's own round-trip tests. Each such patch also silently defines the canonical shape for exactly one type, leaving every other nested type unhandled.
Refines: ARCH-20-001

Commit Authorization and Coverage

ID Priority Requirement Related
CLP-09-001 MUST Every call site of the canonical commit operation MUST reach it only through a role-gated composition, never through a comparison of actor identities. At invocation, that composition checks that the active actor holds CVDRole.CASE_MANAGER for the case.

Any call site that can commit without a check can write an entry from an actor that is not the CASE_MANAGER, and that forks the chain. A check that compares identities fails when one actor holds more than one role, because authority comes from the role (ADR-0088). A role check inside the tree runs for each call site, and the tests can see it.
Refines: BT-10-004
CLP-09-002 MUST NOT The canonical commit operation MUST NOT be invoked directly (bare, unguarded) from any production call site outside the guarded-commit composition itself.

A commit that does not go through the guard can write an entry from an actor that is not the CASE_MANAGER. That forks the chain. When there is one path to the commit, a check in one place covers every call site.
CLP-09-003 MUST Every protocol-significant use case or BT subtree (per BT-06-001) MUST reach a canonical commit for its act. It reaches one more for each further change it makes to the case file (CLP-07-013).

A use case that reaches no commit changes the case at the CASE_MANAGER only, and no replica learns of it. A manual audit finds such gaps late and one at a time. A test over every routed use case finds a missing commit when it is added, as the dispatch tests do for routing (DR-02-002, UCORG-02-002).
Uses definition from: BT-06-001
Derives from: CLP-07-013
CLP-09-005 MUST A coverage test MUST enumerate the protocol-significant entries, such as everything reachable from use_case_map(), and assert that each one reaches a commit (CLP-09-003).

A manual audit finds a missing commit late and one at a time. A test over every routed use case finds it when the use case is added, as the dispatch tests do for routing (DR-02-002, UCORG-02-002).
Verifies: CLP-09-003
CLP-09-006 MUST The coverage test (CLP-09-005) MUST exempt a use case only on a CLP-02-013 ground, or by naming an open issue that tracks its missing commit.

An exemption with no ground hides a missing commit from the test that exists to find it. A CLP-02-013 ground or an open issue makes every exemption a recorded decision.
Extends: CLP-09-005
Uses definition from: CLP-02-013
CLP-09-004 MUST One use-case class may run as more than one receiving actor for one logical activity, such as a relayed copy delivered to a second participant. This codebase MUST then evaluate commit authorization per invocation, against the active actor's role. It never assumes the authorization from the use-case class's identity, or from an earlier authorized invocation.

One use case can run more than once for one activity, for example at the CASE_MANAGER and at a participant that receives a relayed copy. Only the CASE_MANAGER may commit. If the check runs once and its result is reused, a later run as a participant can commit too, and the chain forks.

CASE_MANAGER Inbox Routing for Canonical Ledger Entry Authorship

Requirements for the end-to-end routing path that delivers protocol-significant activities to the CASE_MANAGER's inbox so the CASE_MANAGER can author canonical ledger entries. Covers outbound addressing rules, the rule that the CASE_MANAGER commits its own emissions in the emitting tree rather than addressing a copy to itself (ADR-0109), and the rule that a received-side use case runs its tree only as the receiving actor.

ID Priority Requirement Related
CLP-10-003 MUST NOT A received-side use case MUST NOT run a BT, or call the canonical commit operation, as any actor but receiving_actor_id. Passing a separately resolved case_actor_id to BTBridge.execute_with_setup from the wrong DataLayer context is identity spoofing of this kind.

A use case runs in the store of the actor that received the activity. If it runs a tree as another actor, it writes that actor's state into a store that does not belong to it. The outbox items then carry the wrong sender, and the hash chain can fork. The receiving actor is the only identity the use case may act as.
CLP-10-023 MUST NOT The add_case_ledger_entry_to_ledger semantic type MUST NOT appear in EXPECTED_SEMANTIC_TYPES for the case-actor canonical log.

The invariant suite checks that the canonical log holds each expected semantic type. If that list named the ledger announcement, the suite would demand an entry whose snapshot is an Add(CaseLedgerEntry). CLP-10-004 forbids that entry, so the suite would then reward a broken ledger and fail a correct one.
Derives from: CLP-10-004
CLP-10-005 MUST A received-side use case MUST run exactly one BT per inbox delivery. A call that execute() reaches through any function or method defined under vultron/core/use_cases/ or vultron/core/services/, resolved transitively, counts as a call by execute(). The catch-all for unrecognized semantics (UnknownUseCase) runs no tree. It is not a use case: it refuses the activity before any case is known. A buffered ledger entry that a commit or a case seed makes appliable is its own delivery (SYNC-14-009), never a second run in this one.

Behavior trees exist to compose steps, and the tree is where the guards, the stage order and the checks can see each step. Python code that runs a second tree, or that chooses between trees, puts a protocol decision outside the tree. A helper that execute() calls is part of execute(), so the rule follows it. One tree from one factory keeps each decision where the architecture tests can check it (ADR-0022, ADR-0214).
CLP-10-028 MUST A received-side use case's execute() MUST do exactly three things: build one BT via a tree-factory function in vultron/core/behaviors/, call BTBridge.execute_with_setup() exactly once with actor_id=resolve_receiving_actor_id(self._dl, request.receiving_actor_id) to run it, and handle the result (log or extract output per the Procedural Glue Exception).

A fixed shape makes every received use case read the same way, so the one tree CLP-10-005 requires is easy to find and the receiving actor is resolved in one place for every delivery (ADR-0022).
Refines: CLP-10-005
CLP-10-029 MUST Work that needs more than one tree MUST be composed into the one tree by its factory, never chosen between or run in sequence by Python control flow in the use case. Such work includes a door check, a clock decision (CLP-10-025), a refusal and an alternative branch.

Python code that runs a second tree, or that chooses between trees, puts a protocol decision outside the tree, where the guards, the stage order and the architecture tests cannot see it (ADR-0214).
Refines: CLP-10-005
Uses definition from: CLP-10-025
CLP-10-030 MUST NOT A received-side use case's execute() MUST NOT do domain-significant work beyond running its one tree. That work includes a direct DataLayer mutation, a second execute_with_setup() call, and a direct import or call of create_guarded_commit_case_ledger_entry_tree or any other guarded-commit factory.

Work done in execute() runs outside the tree's guards and stage order. A guarded commit called from execute() lets procedural code decide whether the commit runs (ADR-0021, ADR-0022).
Extends: CLP-10-005
CLP-10-007 MUST Any operation that is procedural code in execute() (including the use case's main operation) MUST be expressed as a node in the single BT tree built by the tree-factory function.

Work that runs as procedural code outside the tree is invisible to the tree's guards and to the checks that read the tree. A node in the tree runs in the stage order, after the guards, and the tests can find it.
Extends: CLP-10-005
CLP-10-008 MUST The guarded-commit subtree MUST be composed as a child of the tree-factory function, not invoked as a separate execute_with_setup() call.

A commit that runs as a separate tree lets procedural code decide whether it runs, outside the guards and the stage order. As a child of the one tree, the commit runs in its stage, after the guards that judge the activity.
Refines: CLP-10-005
CLP-10-006 MUST In any receive-side BT tree that includes a GuardedCommitCaseLedgerEntryBT subtree (composed via create_guarded_commit_case_ledger_entry_tree), the commit subtree MUST appear after the intake node, after the ledger-position answer (SYNC-18-007), after the clock-decision stage (CLP-10-025), and after all pure precondition-guard nodes, and before any protocol-effect nodes. The intake node is the single shared node that archives the received activity as received (CLP-10-017). A precondition-guard node is one that only reads state and returns FAILURE on mismatch, making no writes. A protocol-effect node is any other node that writes to the DataLayer, mutates actor or participant state, or enqueues an outbox item; the intake node is not a protocol-effect node, and neither is a clock decision (CLP-10-025), which commits its own entry, nor the ledger-position answer, which records the sender's replication state and may queue a replay or a re-seed Announce(VulnerabilityCase) but commits no ledger entry and never decides the act's disposition. A refusal effect (CLP-10-022) is a protocol-effect node that runs only when a precondition guard has refused, so the tree fails before the commit; it never runs on a delivery the guards accept, and so never precedes a commit.

Receipt is a fact whether or not the CASE_MANAGER admits the assertion, so the record of what arrived is written before any precondition guard judges it, once the door guards have admitted it (ADR-0214). The commit comes after the guards, so a refused activity commits nothing. Effects come after the commit, so an admitted assertion's effects follow the ledger record of their cause. A refusal effect runs only on a refused path, which has no ledger record and no other effect.
Uses definition from: CLP-10-017
Uses definition from: CLP-10-025
Uses definition from: SYNC-18-007
Uses definition from: CLP-10-022
CLP-10-010 MUST In any receive-side BT tree that includes a GuardedCommitCaseLedgerEntryBT subtree, the ordering MUST be: (1) door guards, in order: the addressee check (HP-01-005), the seen-before door (ADR-0214), the path stage (ADR-0153), the post-close write boundary (CM-23-013), the closed-sender door (CM-23-018) and the sender guard (HP-01-006), (2) intake (CLP-10-017), (2a) the ledger-position answer (SYNC-18-004, SYNC-18-005, SYNC-18-007), (3) clock decisions (CLP-10-025), (4) precondition guards, (5) commit, (6) all protocol effects. Each door guard may end the run, and nothing is written before intake but the post-close reply (CM-23-057), an emit-only answer at the CASE_MANAGER to a late activity the boundary refused. The seen-before door answers a delivery the receiver holds a record for from that record's stage: a receipt stub is REFUSED again with the reason the stub recorded, an archive is SKIPPED, and a record still owed a replay is SKIPPED, and nothing after the door runs, so no refusal notice is sent again; a record in holding that owes no replay lets the delivery through, so a run that ended with no verdict runs again (CLP-10-074). Clock decisions are the only commits before stage (5), other than a diversion (CLP-10-026), which answers its delivery in place of stages (5) and (6). On a delivery the guards admit, the ledger-position answer is the only write before stage (5) besides intake, the clock decisions and a diversion: it records replication state and may queue a replay or re-seed, commits nothing and leaves the disposition of the act to the later stages. Refusal effects (CLP-10-022) belong to stage (4): they run only after a precondition guard refuses, and the tree then ends without reaching (5) or (6). A tree whose message type declares the paths it handles carries the path stage. It asks the receiver's role once and picks the manager, participant-replica or no-case path. It refuses a path the declaration omits, and it writes nothing.

Each door asks a question whose answer can end the run, so the cheapest questions come first and nothing is stored before the last answer: a message that is not for the receiver costs one read and one receipt stub, not a held copy (ADR-0214). Whether the message is addressed to the receiver is asked first. Whether it was seen before is asked next, from the one record that holds it, so a resend is answered from what was recorded and runs nothing (ADR-0214). Inbox runs are serialized per actor, so a resend never meets a run in progress; a record in holding that owes no replay was left by a run that ended with no verdict, and running it again is how it reaches its outcome. Whether a closed case takes the write is a question about the case, asked beside the sender guard once the message is known to be for the receiver. The canonical case ledger records the cause (the received activity the CASE_MANAGER accepted) and replicates it to all participants, so cause precedes effects. A clock decision is the CASE_MANAGER's own act, ledgered even when the activity is then admitted (CM-21-014), so it runs before the guards that read it, and after the door guards so an unentitled sender never makes it write (ADR-0214). The ledger- position answer runs before the guards because it answers the sender's stated position whatever the act's own outcome (SYNC-18-007), and after the door guards for the same reason as a clock decision. The path stage runs among the door guards because the role question decides whether the message is this receiver's to act on at all, and ahead of the sender guard so the guard reads the path instead of asking the same question a second time (HP-01-012).
Uses definition from: CLP-10-017
Uses definition from: CM-23-013
Uses definition from: CM-23-018
Uses definition from: CLP-10-074
Uses definition from: CM-23-057
Uses definition from: HP-01-005
Uses definition from: HP-01-006
Uses definition from: SYNC-18-004
Uses definition from: SYNC-18-005
Uses definition from: SYNC-18-007
Uses definition from: CLP-10-022
Uses definition from: CLP-10-025
CLP-10-011 MUST A receive-side BT tree that applies any protocol effect before committing the triggering activity inverts causal ordering and MUST be corrected.

The ledger records the cause and replicates it to all participants. If effects run first, the ledger can show an effect with no cause, and replicas see a change with no entry that explains it. That makes the ledger unreliable for audit. The entry records that the CASE_MANAGER admitted the activity. A later effect that fails is an operational problem, not a reason to omit that entry.
CLP-10-009 MUST In a receive-side BT composed via create_receive_activity_tree, every node that can return FAILURE to refuse an inbound assertion (a rejection validator) MUST appear in precondition_guards; a rejection validator placed in an effect stage (replica_effects or manager_effects) aborts the Sequence after GuardedCommit has already written a canonical ledger entry, producing canonical/replica divergence (ISSUE-2254). Feedback a refusal owes the sender is passed as refusal_effects (CLP-10-022), never as an emit placed beside the refusing guard.

A guard that runs after the commit can refuse an activity that the ledger already records. The CASE_MANAGER then holds an entry for a change it did not apply, and the replicas apply that change. A refusal must come before the commit to keep the ledger and the case file the same.
Uses definition from: CLP-10-022
CLP-10-012 MUST NOT A separate ValidateRMTransitionNode in an effect stage (replica_effects or manager_effects) MUST NOT be used in the receive-side path; CheckParticipantStatusAcceptableNode judges an inbound ParticipantStatus before the commit (RSH-09-001) and a redundant validator after the commit creates divergence.

A validator after the commit can refuse a change that the ledger already records, so the CASE_MANAGER's case file and the replicas differ. The check that judges an inbound ParticipantStatus already runs before the commit (RSH-09-001). A second check after the commit adds only that risk.
See also: RSH-09-001 — context for the reader
CLP-10-013 MUST A receive-side tree built by create_receive_activity_tree MUST pass case_id when its received activity's (type, object) pair is a canonical payload signature (_CANONICAL_PAYLOAD_SIGNATURES). The CASE_MANAGER then commits one canonical ledger entry for each admitted activity.

An entry is committed only for an activity with a canonical signature. A tree for such an activity that passes no case_id commits nothing, and no replica learns of the admitted act.
CLP-10-033 MUST A receive-side tree MUST pass case_id=None and omit the commit stage when its received activity has no canonical payload signature. An example is the Add(CaseLedgerEntry) replication envelope (CLP-10-004).

A tree that commits an activity with no canonical signature makes the canonical-entry check refuse it, and the handler reports a refusal for a valid delivery.
Extends: CLP-10-013
See also: CLP-10-004 — context for the reader
CLP-10-034 MUST The receive-side trees for Announce(VulnerabilityCase) and for the bootstrap Create(VulnerabilityCase) a participant receives MUST pass case_id=None, although both are canonical signatures. Only the CASE_MANAGER sends them, and only a participant replica receives them (PCR-03-004). The case's genesis entry is committed where the CASE_MANAGER creates the case (CLP-02-013).

A participant never commits. The CASE_MANAGER records the case's creation where it creates the case, so a commit stage in these trees could only refuse a valid delivery.
Supersedes: CLP-10-013
See also: CLP-02-013 — context for the reader
See also: PCR-03-004 — context for the reader
CLP-10-014 MUST A store MUST NOT mint a canonical case-ledger index unless it is the store that holds that case's canonical log.

A log index is a claim on one position in one hash chain. If two stores claim the same position, they fork the chain, and the fork cannot be repaired.
CLP-10-035 MUST CommitLogEntryBT MUST raise, having written nothing, when the actor it executes as is not one the running container hosts.

A participant on another container asks the CASE_MANAGER to act by a message (CM-24-010). So no sanctioned path runs a tree in a store other than its actor's own (BT-05-005, ADR-0109). A tree that does so is a programming error, and the guard raises.
Implements: CLP-10-014
CLP-10-024 MUST A received-side use case MUST NOT use resolve_receiving_actor_id() as the subject a received message names. resolve_receiving_actor_id() is legitimate only as the actor_id passed to execute_with_setup() (CLP-10-005), that is, whose store runs the tree.

resolve_receiving_actor_id() names the actor whose store runs the tree, not the actor the message is about. When the CASE_MANAGER relays a message for a participant, the two differ. A use case that takes the subject from this helper then records the consent or the invitation against the wrong actor (CLP-10-015).
Refines: CLP-10-015
See also: CLP-10-005 — context for the reader
CLP-10-017 MUST Every receive-side BT tree MUST run the shared intake node that create_receive_activity_tree supplies, right after its door guards (CLP-10-010). The record that node writes is the message's one staged record, in holding and not yet at its final stage: what the receiver keeps is decided once the tree has run, by the outcome stage (CLP-10-073).

Receipt is a fact whether or not the receiver admits the assertion, so the record of what arrived is written before any precondition guard judges it. It is written after the door guards, so a message a door turns away costs one read and a receipt stub, never a held copy, and a resend is answered from its record before anything is written (ADR-0214). One shared node gives every received tree the same step (ADR-0214). Keeping the body permanently is a separate question from recording the receipt, and it is answered by the verdict, so the archive a reader loads holds only messages the receiver applied (ADR-0214).
CLP-10-036 MUST The intake node MUST idempotently record the received activity exactly as received, as its ReceivedActivityRecord. The record holds the received body as the parser sealed it (VM-08-002), and nothing derived from it. The receiver derives its id (ReceivedActivityRecord.build_id), never using the id the sender chose. The record carries the sender's activity id for the reverse lookup.

The archive is the sealed body (ADR-0149), because a summary drops what core does not name. The receiver mints the row id, so a sender cannot take an id that the receiver derives for its own record.
Extends: CLP-10-017
Uses definition from: VM-08-002
CLP-10-037 MUST The intake node MUST fail as a wiring fault (ARCH-15-001), archiving nothing, when an activity reaches it with no received body and nothing held.

An archive with no body would record something other than what arrived. The missing body is a wiring bug, so intake fails loudly rather than archive a guess.
Extends: CLP-10-036
Refines: ARCH-15-001
CLP-10-038 MUST NOT The intake node MUST NOT write anything but the archive, such as a core record from an object inlined in the activity. An effect node writes such a record after the precondition guards, from the copy the event carries. Examples are a note, a report, a status, an embargo event and a case replica.

An object inside an activity is only a message shaped like that object. If intake wrote it as a record before the guards, any sender could seed a case replica or a ledger entry ahead of the trust and chain checks (PCR-03-004).
Extends: CLP-10-017
CLP-10-018 MUST A refusal of an inbound assertion MUST leave a receipt stub in the receiver's DataLayer, under the same receiver-derived key as the record it replaces, recording who sent the message, the sender's activity id, the time of receipt, the reason it was refused, and the digest of the body it gave up (IE-10-002). The stub keeps no body (CLP-10-075). A delivery whose body is still owed to a replay is left alone while that replay is owed (CLP-10-076, IO-03-009). A second refusal of the same activity leaves the reason the first recorded (CLP-10-077).

Receipt is a fact and refusal is a verdict on the assertion, not on the record of receipt, so the receipt stays and only the message goes. The refusal itself belongs in the process log, never the ledger (CLP-04-007). A receiver that declines to create a case and still keeps the report and the Offer (CM-15-002) does so as an effect of that policy branch, from the event's copy, not because intake stored them. Keeping the full body of every declined message, including copies never addressed to the receiver, costs storage that grows with refused traffic and gives the receiver content it will never act on; the digest keeps enough to tell a resend of the same body from a reused id without the body (ADR-0214). The cost is that the receiver no longer holds evidence of what a misbehaving sender sent, which is then only in the process log.
See also: IE-10-002 — the digest the stub keeps is what IE-10-002 compares, but refusing a reused id is not a narrower case of what a refusal leaves
See also: IO-03-009 — the body a replay still owes is IO-03-009's hold, named here only to say which delivery this rule leaves alone
CLP-10-019 MUST NOT A received-side use case MUST NOT store the received activity through any path but the intake node. Such other paths include a handler-local helper, a per-tree store node, and a call in execute(). The intake node is the only path that writes the received body; the outcome stage (CLP-10-073) is the only path that moves that record to its final stage, and it is outside the use case.

A second store path can store the activity in a different form, or store it twice. One shared intake node is the DRY form (CS-22-001), and every received tree gets it from the shared factory. The outcome stage writes no body and runs once, after the tree, so it cannot store a second form of the activity (ADR-0214).
See also: CLP-10-073 — the other sanctioned writer of that record, named here so the one-writer rule is read against it; neither is a case of the other
CLP-10-039 MUST NOT A received-side use case MUST NOT write a core record from a received object anywhere but an effect node of its tree.

A core record written in an effect node comes after the guards, so a refused activity writes none (ADR-0214).
Extends: CLP-10-019
CLP-10-021 MUST A received-side use case that tests whether a message is addressed to the receiving actor MUST compare actor ids with a trailing-slash-tolerant comparison (is_addressed_to() or same_actor_id() in vultron/core/predicates/addressing.py), never an exact string match.

to: and cc: arrive as the sender wrote them, and the receiving actor id is canonical. An exact match misses a recipient written with a trailing slash, and the receiver refuses an activity that was addressed to it. Offer(VulnerabilityReport) can have several recipients and reads its eligibility from to: (HP-09-001), so this mistake refuses a valid report.
CLP-10-022 MUST create_receive_activity_tree MUST itself add the refusal notice (CLP-05-001) as the first refusal effect of each tree that commits to a case. This applies to every such tree that has a precondition guard. A tree is exempt only when it names a registered exemption that says what answers its refusals instead.

A refusal the receiver can answer in the moment should be answered. Per-tree copies of the notice would repeat the structure (CS-22-001), so the factory adds it once for every tree.
Implements: CLP-05-005
Uses definition from: CLP-05-001
CLP-10-041 MUST A receive-side tree MUST pass the factory, as refusal_effects, any further feedback it owes the sender when a precondition guard refuses.

An emit beside the guard would precede the commit on an admitted delivery (CLP-10-006). The factory's refusal stage runs the feedback only on a refused path, such as the note for a backward RM declaration (RSH-06-004).
Extends: CLP-10-022
CLP-10-042 MUST The factory MUST run the refusal effects only when a precondition guard refuses. It never runs them when a door guard refuses — the post-close boundary, the addressee check, the path stage or the closed-sender door — when the sender guard refuses, or when the guards pass. Nor does it run them when a guard's failure is an idempotent repeat, which the handler reports SKIPPED.

An unentitled sender is owed no answer (HP-01-006). A repeat whose effect is in place was not refused, so a Reject of it would contradict that effect.
Extends: CLP-10-022
CLP-10-043 MUST The factory MUST run the refusal effects only at the case's CASE_MANAGER.

Only the CASE_MANAGER adjudicates and answers (BT-17-008). A replica that ran them would answer a refusal it did not make.
Extends: CLP-10-022
CLP-10-044 MUST NOT The factory MUST NOT run the refusal effects again for a redelivery that intake found already archived.

The first delivery already answered the refusal. A second answer for a redelivery would tell the sender twice about one refusal.
Extends: CLP-10-022
CLP-10-045 MUST The factory MUST run each refusal effect whether or not an earlier one failed.

One failed effect should not cost the sender the others. The refusal notice comes first, so a later effect must not depend on it.
Extends: CLP-10-022
CLP-10-046 MUST The factory MUST leave the tree failing with the guard's refusal. So nothing of the refused assertion is committed, and the handler reports REFUSED for the guard's reason.

The refusal effects answer the refusal; they do not change it. If an effect's result replaced the guard's, the handler could report a refused assertion as applied, or with the wrong reason.
Extends: CLP-10-022
CLP-10-047 MUST Every refusal effect MUST be emit-capable.

A refusal effect exists to answer the sender, so a node that cannot emit has no place among them. The factory refuses one at build time.
Extends: CLP-10-022
CLP-10-048 MUST NOT A refusal effect MUST NOT contain a state-write node, because a refusal commits nothing of the assertion. The one exception is the CASE_MANAGER's own note (_CommitCaseManagerNoteBase, RSH-06-004). It commits itself as its own add_note_to_case entry before it attaches the note to the case.

A refusal changes no state the ledger does not record. A state write in a refusal effect would change the case with no entry for it.
Extends: CLP-10-022
Uses definition from: RSH-06-004
CLP-10-025 MUST A receive-side tree MUST pass each decision the CASE_MANAGER takes from its own clock or local policy to create_receive_activity_tree as a clock decision. This covers each such decision that the CASE_MANAGER must record before it judges the received activity, such as an invitation expiry (CLP-07-013, CM-28-009). A decision that changes nothing in the case file records nothing, and is not a clock decision. An ownership-transfer Offer's expiry is one (CM-21-043, ADR-0152).

An expiry must be in the ledger even when the activity that revealed it is then admitted, so it cannot be a refusal effect or wait for the activity's commit. A separate tree would break the one-tree rule (CLP-10-005). A named stage keeps the decision in the one tree (ADR-0214).
Implements: CLP-07-013
Constrains: CM-28-015
See also: CM-21-043 — context for the reader
See also: CM-28-009 — context for the reader
CLP-10-049 MUST The factory MUST run the clock decisions after the door guards and before the precondition guards (CLP-10-010).

The stage runs after the sender guard, so a sender with no standing cannot cause a termination. It runs before the guards that read what it records.
Extends: CLP-10-025
Refines: CLP-10-010
CLP-10-050 MUST The factory MUST run the clock decisions only at the case's CASE_MANAGER (BT-17-001).

Only the CASE_MANAGER commits ledger entries. A replica that ran a clock decision would write a case change no entry records.
Extends: CLP-10-025
Refines: BT-17-001
CLP-10-051 MUST This rule covers each receive-side tree that names a case and has a sender guard and the post-close boundary. Each such tree MUST take the embargo end-time check (EMB-13-003) as a clock decision. The factory adds it with no argument from the tree. A tree still exempt from a sender check takes it once it declares its sender rule (HP-01-007).

Any activity on an overdue case can reveal that its embargo has ended. The factory adds the check itself, so a new tree cannot forget it, and the sender guard keeps a non-participant from causing a termination.
Extends: CLP-10-025
Uses definition from: EMB-13-003
Uses definition from: HP-01-007
CLP-10-052 MUST A clock decision MUST commit only CASE_MANAGER-authored entries, one for each AS2 activity needed to express what it decided. It also commits the case-file changes those entries record, and nothing about the received activity. An expiry is one entry. An end-time termination is the Remove(EmbargoEvent) and each status update and re-issued stub Invite it needs.

The decision runs before the guards. If it committed the activity's own effects, a refused activity would leave a change in the ledger (ADR-0214).
Extends: CLP-10-025
CLP-10-053 MUST A clock decision MUST order its entries so that no prefix of them leaves an embargo register entry TERMINATED while another is PROPOSED (EP-08-004, ADR-0122). The Remove carries the whole register step, the cancellation of every open proposal included.

A replica that applies only the first entries of the decision must still hold a register that obeys EP-08-004. The Remove cancels every proposal in the same step, so no prefix breaks it.
Extends: CLP-10-025
Derives from: EP-08-004
CLP-10-054 MUST A clock decision MUST take its evidence only from the CASE_MANAGER's clock, its local policy, and the case's ledger and file. It never takes it from the received activity.

A sender controls what its activity claims. If the activity were the evidence, a sender could decide a deadline by the time it writes.
Extends: CLP-10-025
CLP-10-055 MAY The received activity MAY prompt a clock decision and name what the decision concerns.

The CASE_MANAGER decides lazily, when an activity about the case arrives, so the activity can be the occasion of a decision without being its evidence.
CLP-10-056 MAY A clock decision's entry MAY carry the received activity's claimed published time as received (CLP-15-003). The time records when the activity claims to have been sent, and decides nothing.

A reader of the ledger can then see when the prompting activity claims it was sent, beside the CASE_MANAGER's own commit stamp.
Uses definition from: CLP-15-003
CLP-10-057 MUST A clock decision with nothing to record MUST succeed, so the tree continues. An example is a decision where no deadline has passed.

Most deliveries find no deadline passed. If such a decision failed, it would refuse every activity that arrived on time.
Extends: CLP-10-025
CLP-10-058 MUST A clock decision whose commit the ledger refuses MUST log the refusal at WARNING.

The decision is left unrecorded, which an operator should see. The guards still refuse what it forbids, so the case is safe, and WARNING fits a recoverable condition.
Extends: CLP-10-025
CLP-10-059 MUST NOT A clock decision whose commit the ledger refuses MUST NOT end the tree. The precondition guards still refuse what the unrecorded decision forbids (EMB-17-001).

A gapped ledger can refuse the decision's commit. Ending the tree would then refuse an activity the guards would admit, for a fault that is not the sender's.
Extends: CLP-10-025
See also: EMB-17-001 — context for the reader
CLP-10-060 MUST An internal error in a clock decision MUST end the tree as an internal error (ADR-0095), never be absorbed as a refusal.

An internal error is a bug. If it read as a refusal, the sender would be told its activity was refused and the bug would stay hidden.
Extends: CLP-10-025
CLP-10-026 MUST A receive-side tree MUST pass each answer it gives in place of a commit to create_receive_activity_tree as a diversion among its precondition guards. Such an answer is an act of the receiver's own that answers a delivery instead of committing the received activity. Examples are the CASE_MANAGER's answer to a late embargo Accept (EMB-17), and a receiver's Reject of the Invite once P/X/A is set (EMB-01-002, EMB-02-004, EMB-03-004). The tree, not the use case, then chooses the answer (CLP-10-005). A tree with diversions still answers the refusals its guards make with the refusal notice (CLP-02-005).

Some deliveries get an answer from the receiver in place of the admitted path. If the use case chooses between trees to give that answer, the choice is outside the tree, which the one-tree rule forbids (ADR-0214). These answers are not refusal effects. The late-Accept answer commits and writes consent. The P/X/A Reject of the Invite is owed by a participant too, and its derived id lets a redelivery find it already sent (HP-01-014). A diversion keeps each answer in the one tree, where tests and readers can see it.
Refines: CLP-10-005
Refines: CLP-10-010
See also: CLP-02-005 — context for the reader
See also: EMB-01-002 — context for the reader
See also: EMB-02-004 — context for the reader
See also: EMB-03-004 — context for the reader
CLP-10-061 MUST A diversion MUST have a read-only condition.

The condition runs before the commit on every delivery, including those it does not divert. A condition that wrote state would change the case for a delivery that the admitted path then handles.
Extends: CLP-10-026
CLP-10-062 MUST When a diversion's condition holds, the diversion's effects MUST answer the delivery.

The diversion exists to give the receiver's own answer in place of the admitted path. A diversion that took a delivery and answered nothing would leave the sender waiting.
Extends: CLP-10-026
CLP-10-063 MUST When a diversion's condition holds, the tree MUST end before the received activity's commit. So that commit and the admitted path's effects never run for the delivery.

A diverted delivery has been answered in another way. If the admitted path also ran, one delivery would get two contradictory outcomes.
Extends: CLP-10-026
CLP-10-064 MUST NOT A diversion MUST NOT commit the received activity.

A diversion answers in place of admitting the activity. A commit of the activity would admit it while the diversion refused it.
Extends: CLP-10-026
CLP-10-065 MUST A diversion that commits or writes case state MUST run only at the case's CASE_MANAGER (BT-17-001).

Only the CASE_MANAGER writes canonical case state. A replica that ran such a diversion would write a change no entry records.
Extends: CLP-10-026
Refines: BT-17-001
CLP-10-066 MUST A diversion that commits MUST commit only its own CASE_MANAGER-authored entry and the change that entry records.

The late-Accept answer commits and writes consent, which must be in the ledger. Anything more would put the received activity's own effects ahead of the guards.
Extends: CLP-10-026
CLP-10-067 MUST A diversion that answers as the receiver, wherever the door guards admitted the delivery, MUST write no case or participant state (RSH-08-003).

Such a diversion runs at participants as well as at the CASE_MANAGER, and a participant takes case state only from the ledger (RSH-08-003). The P/X/A Reject of the Invite is owed by a participant too.
Extends: CLP-10-026
See also: RSH-08-003 — context for the reader
CLP-10-068 MAY A diversion that answers as the receiver MAY store the activity it answers, so that it can build its answer from it.

The answer embeds or names the activity it answers. Storing it lets the answer be built from what arrived, and its derived id lets a redelivery find the answer already sent (HP-01-014).
CLP-10-069 MUST Every emit in a diversion that answers as the receiver MUST be covered by a named exemption (BT-17-008).

An emit outside the CASE_MANAGER gate needs a stated reason, or any tree could speak for an actor it does not run as (BT-17-008).
Extends: CLP-10-026
Uses definition from: BT-17-008
CLP-10-070 MUST The factory MUST run no refusal effect for a diverted delivery (CLP-10-022), because the diversion has already answered it.

A refusal notice after a diversion's answer would tell the sender two different things about one delivery.
Extends: CLP-10-026
Uses definition from: CLP-10-022
CLP-10-027 MUST In this codebase, every protocol-significant trigger tree MUST emit at least one outbound activity addressed to case_manager_id (CLP-10-001).

The CASE_MANAGER is the only writer of the case ledger, so an assertion that never reaches it is never committed and the act is lost.
Implements: CLP-10-001
CLP-10-071 MUST A tree the CASE_MANAGER runs to originate an activity MUST emit from its own store, and commit the canonical entry in the emitting tree (CLP-10-031). An example is invite_actor_to_case.

The CASE_MANAGER's store holds the canonical ledger, so its own act is committed where it is sent, with no copy addressed to itself.
Implements: CLP-10-031
CLP-10-072 MUST NOT A participant whose container does not host the CASE_MANAGER MUST NOT execute a tree locally as the CASE_MANAGER (CM-24-011).

Running a tree as the CASE_MANAGER in a container that does not host it would write canonical state into a store no replica reads.
Refines: CLP-10-001
Refines: CM-24-011
CLP-10-073 MUST One outcome stage, outside the handling tree and after it, MUST map the handler's disposition onto the received record's final stage: an APPLIED or SKIPPED delivery keeps the sealed body the record holds, which moves from holding to the archive (CLP-10-017); a REFUSED delivery leaves a receipt stub and no body (CLP-10-018); a DEFERRED delivery leaves the holding record as the wait left it (IO-03-009). The stage reads that disposition from the handler's result, the handler's only channel to the inbox (UCORG-05-010), and not from state an earlier stage left in memory (CLP-10-078). It records the outcome and never decides one (CLP-10-079).

Every stage reads the record, the store and the one input its boundary hands over (CLP-10-084), so a later stage cannot be fooled by what an earlier one happened to leave in memory (ADR-0214). One stage rather than a write in each tree means a tree cannot forget it or disagree with another about what a refusal keeps (CS-22-001). It runs after the tree because a node in the run embeds the body of the message being handled — the refusal notice does (CLP-05-001) — so the body must still be there while the tree runs.
Uses definition from: CLP-10-017
Uses definition from: CLP-10-018
Uses definition from: IO-03-009
Uses definition from: UCORG-05-010
CLP-10-074 MUST A delivery that produced no handler verdict MUST leave the received record exactly as it is, in holding with its sealed body. That covers a dispatch that raised and a dispatch that returned no HandlerResult. A semantic type no use case handles (IO-01-005) is not such a delivery: it is REFUSED, so it leaves a receipt stub and no body (CLP-10-018).

A dispatch that raised is not a verdict on the assertion, so it is not an outcome. The act rolled back and kept nothing (ADR-0214), so a resend or a re-run must be able to run it again from the body the receiver holds; reducing that record to a receipt stub would record a refusal the receiver never made and take the body the re-run needs (ADR-0214). A message no use case handles is different: nothing will ever apply it, its disposition is REFUSED, and keeping its body would let any sender make the receiver keep an arbitrary body indefinitely by choosing a type the receiver does not handle (ADR-0214: a message the receiver will not act on costs one read and one stub, not a permanent copy).
Refines: CLP-10-073
Uses definition from: IO-01-005
Uses definition from: CLP-10-018
CLP-10-075 MUST NOT A receipt stub MUST NOT keep the received body.

Keeping it would make the refusal cost the same storage as an applied message, permanently, for content the receiver will never act on, which is what the stub exists to avoid (ADR-0214). The digest the stub keeps is enough to tell a resend of the same body from a reused id (IE-10-002).
Refines: CLP-10-018
CLP-10-076 MUST NOT The outcome stage MUST NOT reduce to a receipt stub a delivery whose body is still owed to a replay.

The replay routes that body (IO-03-009), so dropping it would lose the message the wait exists to deliver. The hold ends first, through the holding service, and only then is there a body to give up.
Refines: CLP-10-018
Uses definition from: IO-03-009
CLP-10-077 MUST When the outcome stage records a refusal for a record that is already a receipt stub, it MUST leave the reason the first refusal recorded.

A refusal is whole and final for that activity, so the record of why it was refused is the first verdict's; a later refusal would otherwise rewrite history (ADR-0214). The seen-before door answers a resend of a refused message from its stub before intake runs, so nothing writes over the stub and the first reason is the one a resend is refused with.
Refines: CLP-10-018
CLP-10-078 MUST NOT The outcome stage MUST NOT decide the received record's final stage from in-memory state an earlier stage left behind.

Every stage reads the record, the store and the one input its boundary hands over (CLP-10-084), so a later one cannot be fooled by what an earlier one happened to leave in memory (ADR-0214). The handler's result is the one channel from the handling tree (UCORG-05-010); whether a delivery was seen before is a question for the record.
Refines: CLP-10-073
Uses definition from: UCORG-05-010
CLP-10-079 MUST NOT The outcome stage MUST NOT change the verdict the sender is answered with.

The stage records an outcome the handler already decided. A failure to record it over-retains a refused body, which is a bookkeeping fault, while rewriting the verdict would answer the sender for a reason no guard gave (MV-01-007).
Refines: CLP-10-073
CLP-10-080 MUST When intake finds a HELD record that owes no replay, it MUST move the record to HANDLED and keep its body.

A run that ended with no verdict, or a process stop, leaves the record in holding, and the next run handles the message again (CLP-10-074). The first run may already have answered the ledger position, judged the sender's number or answered a refusal. Intake is the one stage that can tell the two runs apart: no earlier write marks a first run, and a later write would leave a crash window in which a re-run reads as a first run (ADR-0214).
Refines: CLP-10-074
CLP-10-082 MUST A stage after intake that answers a delivery only once MUST read whether its run is a re-run from the record's stage, not from in-memory state that an earlier stage wrote.

Memory does not survive a restart, and a door that keeps its answer in memory ties the stages that read it to one run of one process (ADR-0214). The record carries the answer (CLP-10-080).
Uses definition from: CLP-10-080
CLP-10-081 MUST A received tree that runs inside another received tree for the same delivery MUST run no seen-before door and no intake of its own.

The enclosing tree's door answered the delivery, and its intake recorded it. A second intake would find that record and read a first run as a re-run (CLP-10-080). The nested tree runs as an effect of the enclosing one, whose stages follow the CLP-10-010 order.
Refines: CLP-10-017
Refines: CLP-10-010
CLP-10-083 MUST A delivery whose run ended with no handler verdict MUST be run again from its door guards, never resumed at a later stage.

A run that starts over asks every door question again, so no stage depends on an answer that only an earlier, lost run held in memory (ADR-0214). The record tells the re-run what the first run already did (CLP-10-080), and every handling tree tolerates the second run. Resuming at a later stage would need each door answer kept on the record, a persistence change no use needs.
Refines: CLP-10-074
Uses definition from: IE-06-014
CLP-10-084 MUST NOT A handling-tree node MUST NOT read in-memory state a door stage left behind, other than the receiver's path that the HP-01-035 stage resolved.

Each stage boundary hands over one named input: the delivery to the doors, the resolved path to the handling tree and the handler's result to the outcome stage (CLP-10-073). The path is read from the door, not asked again, because an act such as an ownership transfer changes who the CASE_MANAGER is partway through the run (HP-01-036). Every run starts at the doors (CLP-10-083), so the path always comes from the same run and a restart loses nothing.
Refines: CLP-10-082
Uses definition from: HP-01-035
Uses definition from: HP-01-036

Protocol Request/Reply State Detection

Requirements for querying whether a protocol-level request/reply pair (e.g., Offer(CaseParticipant) → Accept/Reject) is still open or has been closed. These rules establish the canonical pattern for duplicate-emission suppression and CASE_MANAGER decision-gate checks.

ID Priority Requirement Related
CLP-11-002 MUST NOT find_protocol_pair() (durable, DataLayer-backed) and PendingAssertionStore (ephemeral, in-memory suppression) MUST NOT be unified. They serve distinct purposes: find_protocol_pair determines canonical open/closed state from the ledger; PendingAssertionStore suppresses duplicate near-term re-emits while waiting for the CaseLedgerEntry round-trip. Merging them would conflate durable protocol state with short-lived emit-suppression state.

The ledger record is durable and decides whether a request is open. The suppression record is short-lived and only stops a repeat send. If they are one store, code can read a short-lived record as protocol state, or keep durable state in memory that a restart removes.
CLP-11-003 MUST ProtocolPair MUST be the shared value type for both find_protocol_pair() and PendingAssertionStore.

Both stores answer questions about the same request and reply. One type lets code move between them with no conversion.
CLP-11-006 MUST Code that constructs or queries a ProtocolPair MUST use the named reply-type constants (OFFER_CASE_PARTICIPANT_REPLY_TYPES, INVITE_ACTOR_TO_CASE_REPLY_TYPES), never reply semantic-type strings written at the call site.

Named constants keep every call site on one list of reply types, so a new reply type is added in one place.
Extends: CLP-11-003
CLP-11-004 SHOULD When find_protocol_pair() searches for a reply entry, it SHOULD use the semantic_type field of CaseLedgerEntry (derived from MessageSemantics.value) as the primary key, scoped to case_id.

The semantic type of an entry names the reply exactly, and the case scope keeps the search inside one ledger. A search that follows in_reply_to chains depends on how each sender set that field.
CLP-11-007 MUST NOT This codebase MUST NOT expose in_reply_to chain-following as a public port primitive. It stays an internal detail of the implementation.

A port that exposes chain-following makes every adapter copy that detail, and binds callers to how each sender set in_reply_to.
Extends: CLP-11-004
CLP-11-005 MUST This codebase MUST answer whether a request/reply pair has been authorized (CLP-11-001) through CasePersistence.find_protocol_pair(), which queries the case ledger.

One query over the case ledger gives every caller the same answer to whether a request was already answered. Separate checks over other stored records can disagree with the ledger and with each other.
Implements: CLP-11-001

Idempotency Guard Silence

Requirements ensuring that BT idempotency guards (duplicate-detection conditions that abort processing when an event has already been handled) do NOT write ledger entries. The canonical case ledger records protocol assertions; internal guard no-ops are process-log content only (ADR-0019).

ID Priority Requirement Related
CLP-13-001 MUST NOT A BT idempotency guard that detects a duplicate and returns Status.FAILURE to abort processing MUST NOT write a CaseLedgerEntry.

A duplicate that a guard stops is not a protocol event. An entry for it appears in the shared history as an act that changed nothing, with no actor and no transition. The ledger records the event or stays silent (ADR-0019), so the duplicate belongs in the process log.
Refines: CLP-07-001
CLP-13-002 MUST Idempotency guard behaviour MUST be encapsulated in a reusable SilentIdempotencyGuardMixin (or equivalent composable BT pattern) so that the silent-failure-on-duplicate invariant is expressed once and tested once, not re-implemented per call site.

Separate duplicate checks at each call site drift apart. A new call site can then write a ledger entry on a no-op by mistake. One shared pattern holds the silent-on-duplicate rule in one place, and one test covers it.
Implements: CLP-13-001
CLP-13-003 MUST When an idempotency guard fires and returns Status.FAILURE, it MUST emit a Python logger.info or logger.debug message recording the duplicate detection. No other observable side effect (ledger write, outbox enqueue, DataLayer mutation) is permitted.

A silent guard leaves no entry, so an operator needs a log line to see that a duplicate arrived and why nothing happened. A low log level keeps an ordinary redelivery from looking like a fault. Any other side effect would make the duplicate change state, which the guard exists to stop.
Extends: CLP-13-001

CaseLedger Causal Ordering — CASE_MANAGER Timestamp Invariants

Normative requirements establishing that log_index order is the canonical causal order from the CASE_MANAGER's perspective, and the temporal invariants that conformance tests can verify against any ledger. See ADR-0079 for the decision record and rationale.

ID Priority Requirement Related
CLP-14-009 MAY Implementations MAY expose the future tolerance (CLP-14-007), the staleness window (CLP-14-008) and the clock-skew tolerance applied to the claimed-timestamp checks (CLP-14-013, CLP-15-003) as configurable parameters so that deployments with known clock conditions can tune the thresholds.

Each threshold compares a participant's clock with the CASE_MANAGER's clock. How far apart those clocks are is a fact of the deployment, and the protocol cannot know it. So every such threshold needs the same setting, and none of them may be fixed in code.
Uses definition from: CLP-14-007
Uses definition from: CLP-14-008
See also: CLP-15-003 — context for the reader

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-010 MAY One actor MAY enact the CASE_MANAGER and also be the Case Owner (the named actor).

A deployment may enact both roles in one actor. An actor holding both roles still routes case traffic through its CASE_MANAGER role (CBT-01-014).
CM-02-019 MUST Two different actors enacting the CASE_MANAGER and the Case Owner MUST each have their own actor ID, even on one server.

When the proposal flow (CP-09-001) yields two actors, distinct identities keep every case-state transition on the wire protocol, whatever the topology. They also let the two actors separate later without protocol changes.
Extends: CM-02-010
Derives from: CM-01-001
CM-02-015 MUST When a VulnerabilityCase is created via the direct-mint path (e.g. trigger/create-case, without a Create(CaseProposal) round-trip), the creating actor MUST be registered as a CaseParticipant carrying both CVDRole.CASE_OWNER and CVDRole.CASE_MANAGER as part of the same atomic case-creation operation.

In the direct-mint path there is no intermediary proposer; the creating actor is the sole authority holder from the start and holds both roles until it delegates CASE_MANAGER via an Offer(role) → Accept exchange. Deferring or omitting participant registration means the case roster is empty at birth, violating CM-02-014 and breaking any caller that queries the role ledger immediately after creation.
Refines: CM-02-014
CM-02-016 MUST When the CASE_MANAGER commits an accept_case_participant_role ledger entry, it MUST grant the offered CVDRole to the target Actor's CaseParticipant on its own replica. That entry records the acceptance of an Offer(CaseParticipantRole) (ADR-0039).

An Offer(CaseParticipantRole) is a proposal, not the grant. The role changes only when the CASE_MANAGER commits the acceptance. The CASE_MANAGER applies the grant to its own copy at commit. This keeps the authority for roles with the CASE_MANAGER and keeps every replica the same (ADR-0108, ADR-0124). The CASE_MANAGER's replica is the one its later checks read, such as whether the target already holds a role (CM-33-003).
Extends: CM-33-006
CM-02-020 MUST Every participant other than the CASE_MANAGER MUST grant the offered CVDRole to the target Actor's CaseParticipant when it replays a committed accept_case_participant_role entry (RSH-08-004).

The CASE_MANAGER's ledger is the authority for roles. Every other replica learns of the grant only from the entry, so it applies the grant when it replays that entry. Then every replica holds the same roles (ADR-0108, ADR-0124).
Extends: CM-02-016
Refines: RSH-08-004
CM-02-021 MUST NOT A participant MUST NOT change case_roles directly from an Accept of an Offer(CaseParticipantRole) that it receives.

Only a committed ledger entry grants a role (CM-02-016, CM-02-020). If a participant changes case_roles from an Accept that it sees directly, it can have a role that the ledger did not grant.
Extends: CM-02-016

Case State Model

ID Priority Requirement Related
CM-03-006 MUST Collection fields that hold status histories MUST be pluralized and documented as history collections

A reader reads a status field that holds a history differently from a field that holds a current value. A plural name and documentation that calls the field a history prevent two errors. The reader does not take the latest entry as the full record, or the full record as one value.

Object Model Relationships

ID Priority Requirement Related
CM-05-013 MUST This codebase MUST model VulnerabilityReport, VulnerabilityCase, VulnerabilityItem, CaseReference, CaseParticipant, and ParticipantStatus as separate types.

CM-05-001 states only what other participants observe (MS-12-010). This requirement records how this codebase satisfies CM-05-001. Separate types keep the validation rules of each object in one place. The Case Actor is not in this list. It is an ordinary VultronService that holds the CASE_MANAGER role, not a different type (ADR-0088).
Implements: CM-05-001
CM-05-016 MUST NOT This codebase MUST NOT substitute one of the six types of CM-05-013 for another at any API boundary or in the persistence layer.

How this codebase meets CM-05-015. Separate types let the type checker find an object that the code passes in place of a different object.
Implements: CM-05-015
Uses definition from: CM-05-013
CM-05-014 SHOULD This codebase SHOULD log a warning when a VulnerabilityCase closes with no associated VulnerabilityItem (CM-05-003).

How this codebase reports a miss of CM-05-003; split from it so CM-05-003 states only what the case carries (MS-12-010). A log line is not something another participant can observe.
Verifies: CM-05-003

CVD Action Rules API

ID Priority Requirement Related
CM-07-002 MUST The action rules response MUST include the participant's role and the current RM, EM, CS, and VFD states relevant to that participant

A client must know the state that produced the list of valid actions. It uses that state to explain the list to a user and to find when the list is stale. The role and the related states in the response give that context.
CM-07-003 MUST The action rules response MUST list valid next actions as structured objects including the action name and any required parameters

A client uses the response directly. Structured objects with the action name and its parameters let the client build the request. The client does not parse prose or hard-code which action needs which input.

Domain Model Architecture

ID Priority Requirement Related
CM-08-002 MUST NOT A core domain class in this codebase MUST NOT inherit directly from an ActivityStreams base type. Its AS2 serialization goes through the rendering port (ARCH-20-001, ADR-0211).

The two branches stay distinct type hierarchies, so neither branch imports the other. The rendering port gives core a wire form without core code building it (notes/wire-core-boundary.md).
Refines: CM-08-001
See also: ARCH-20-001 — context for the reader
CM-08-003 MUST NOT A wire class in this codebase MUST NOT carry a translation method to or from a core domain object.

The translation between the two branches lives on the adapter side, the one layer permitted to see both. A translation method on a wire class would make the wire branch import the core branch.
Refines: CM-08-001

Redacted Case View

ID Priority Requirement Related
CM-09-004 MAY For the prototype, the stub Invite MAY carry the case stub of CM-11-013, which names the full case ID, deferring the redacted view to a later phase.

The redacted view (CM-09-001) is a production feature that the prototype does not have. The stub Invite of the prototype carries the case stub of CM-11-013, so invitations work from start to end without the redacted view. The cost is that the invitee sees the full case ID. CM-09-002 forbids this only for a RedactedVulnerabilityCase.
Uses definition from: CM-11-013

Case Creation Timing

ID Priority Requirement Related
CM-12-001 MUST When a report receiver's auto_create_case is True (CM-15-001), it MUST propose a case to the CASE_MANAGER for each Offer(VulnerabilityReport) it receives (CP-04-001). The CASE_MANAGER, not the receiver, creates the VulnerabilityCase (CP-09-001).

The vendor that receives a report is the first party that must act on it. When it proposes the case at receipt, the report has a case, and its participants have an RM state, from RM.RECEIVED onward. The receiver does not create the case itself, because the CASE_MANAGER is the case's authoritative creator (ADR-0041). With auto_create_case set to False, no case starts (CM-15-003).
Uses definition from: CM-15-001
Uses definition from: CP-04-001
See also: CP-09-001 — context for the reader
CM-12-005 MUST InvalidateReportReceivedUseCase, CloseReportReceivedUseCase, and ValidateReportReceivedUseCase MUST dereference the incoming report ID to the associated case ID before delegating to the corresponding case-level use case

The report-level messages name the report. But each participant's RM state that these messages change is on the case. When the use case resolves the report to its case first, one case-level use case applies the change. Thus the report-level path and the case-level path cannot become different.

Embargo Acceptance Ownership

ID Priority Requirement Related
CM-13-009 MUST The embargo accept and reject use cases MUST succeed silently when the participant's consent row for the embargo is already AGREED (for accept) or DECLINED (for reject), without re-running state machine transitions or emitting invalid-transition warnings.

How this codebase meets CM-13-005; split from it so CM-13-005 states only what other participants observe (MS-12-010).
Implements: CM-13-005
CM-13-006 MUST When a case is created with a default embargo that reaches EM.ACTIVE at creation time, the Case Owner MUST be initialized as a signatory in the same BT node or an immediately following sibling node in the same BT subtree

The case creator is the Case Owner by default; seeding them as a signatory prevents the Case Owner from being locked out of their own active embargo until a separate accept step occurs. The consent state must be set via the PEC state machine (not by direct field assignment) to preserve state machine invariants.
CM-13-007 MUST This codebase MUST treat a received Add(Note) as an idempotent redelivery only when the case's ledger already records that same Add. A note stored in the DataLayer under that id refuses a new Add instead (HP-08-006).

A note stored under an id does not show that this Add attached the note to this case. The note can belong to a different case, or to a different Add. If the receiver used the stored note as the idempotency test, an Add that names the note of a different case would pass as a redelivery. The ledger shows that this case already took this Add.
Constrains: HP-08-006
CM-13-010 MUST The note attach step MUST test whether the note's id_ is present in VulnerabilityCase.notes, never whether the note is stored in the DataLayer.

A note stored under an id can belong to a different case. The case's own notes list shows that this case already holds the note.
Extends: CM-13-007

Case Creation Policy

Requirements for the configurable auto_create_case policy on ActorConfig, which controls whether a VulnerabilityCase is created automatically upon receipt of an Offer(VulnerabilityReport).

ID Priority Requirement Related
CM-15-001 MUST ActorConfig MUST expose an auto_create_case boolean field with a default value of True.

Receivers that acknowledge a report (send Read(Offer(VulnerabilityReport)), VAM-02-003) before deciding to accept or reject it require the ability to delay case creation. The default (True) starts a case at every Offer(VulnerabilityReport) receipt (RM.RECEIVED) for all existing actors and demos; the receiver proposes it and the CASE_MANAGER creates it (CM-12-001, CP-09-001).
CM-15-002 MUST When a receiver's auto_create_case is False, processing an inbound Offer(VulnerabilityReport) MUST store the VulnerabilityReport and the Offer(VulnerabilityReport) activity in the DataLayer.

The report materials must be persisted even when case creation is suppressed so that they can be retrieved if the operator later enables case creation or reviews the offer manually.
CM-15-003 MUST NOT When a receiver's auto_create_case is False, processing an inbound Offer(VulnerabilityReport) MUST NOT create a VulnerabilityCase.

The purpose of the flag is to suppress automatic case creation; creating a case anyway would make the flag meaningless.
CM-15-004 MUST When a receiver's auto_create_case is False, processing an inbound Offer(VulnerabilityReport) MUST leave the receiver's outbox unchanged (no outbound activities are enqueued).

Suppressing case creation also suppresses the associated outbound activities (e.g., Create(VulnerabilityCase) to the reporter); the observable outcome is no outbound messages.
CM-15-005 MUST The auto_create_case gate MUST be enforced as an in-tree condition node in create_receive_report_case_tree, after the intake node and ahead of any case-creating effect. A routing-level short-circuit in SubmitReportReceivedUseCase is not a conforming enforcement location, because it stores the report and the Offer(VulnerabilityReport) before any tree runs (CLP-10-019). The observable outcome (no case, no outbound activities; report and Offer stored per CM-15-002) remains normative.

Case creation is protocol-significant behavior (BT-15-001). Thus the gate is a condition node in the behavior tree. A short-circuit in the use case must store the report and the Offer before it returns. That is a store path outside the tree, which CLP-10-019 forbids. The tree stores the report and the Offer for every addressed inbound Offer(VulnerabilityReport) (ADR-0214). Thus a gate outside the tree has nothing to do.
See also: CLP-10-019 — context for the reader
See also: CM-15-002 — context for the reader
CM-15-006 SHOULD The auto_create_case=True default in ActorConfig is a reference implementation choice, not a Vultron protocol requirement. An implementation that sets auto_create_case=False creates the case in a later, separate step (for example SvcCreateCaseUseCase with the report's report_id); once that case is linked to the report, the implementation SHOULD close it through the leave-case trigger (the Case Owner's Leave(VulnerabilityCase), TRIG-13-001) when the operator or user requests closure, as with an auto-created case.

The protocol does not say when to create a case. Thus auto_create_case=True is a choice of this reference implementation, and other implementations do not have to copy it (ADR-0085). When a case holds the report, its Case Owner closes the case with Leave, as for a case created automatically. No trigger sends Reject(Offer(VulnerabilityReport)) for the case (CM-23-019, ADR-0145). With one closure path, a case created in a later step does not need a second path.
Uses definition from: TRIG-13-001

Actor Suggestion Routing (Recommend-Actor Flow)

ID Priority Requirement Related
CM-16-003 MUST After recording the received Offer(Actor), the CASE_MANAGER MUST assign a non-empty default role list for the suggested actor via an Evaluator BT node (ADR-0024 shape: Evaluator). This applies to a suggested actor, where the CASE_MANAGER chooses the roles through its policy hook; the Case Owner's own stub Invite names its roles and guesses none (CM-11-019).

A suggestion names only an actor. But the stub Invite must carry at least one role (CM-11-019). Thus the CASE_MANAGER must choose a role. The correct role is a policy decision. Thus the choice is an Evaluator call-out (ADR-0024) that a deployment can replace. The CASE_MANAGER writes only a list that is not empty. Thus no later node has to read an empty list as a signal.
See also: CM-11-019 — context for the reader
CM-16-011 SHOULD The default role list SHOULD be [CVDRole.VENDOR] for actors whose type cannot be determined from context, because in CVD cases the most likely role for a newly added participant is Vendor.

A default that fits most suggestions lets the Case Owner usually accept the default without a change. When the default does not fit, the Case Owner can change it when it accepts (CM-16-013).
CM-16-012 MAY The default role list MAY be [CVDRole.OBSERVER] when the Evaluator can determine that the suggested actor does not fit any known CVD role but still requires case membership (e.g., a security researcher with no vendor affiliation). CVDRole.OBSERVER is the most conservative choice because it makes no assumption about the actor's function in the CVD process beyond case observation (CM-25-001).

An actor that fits no CVD role must also see the case. CVDRole.OBSERVER lets the actor see the case without the obligations or the authority of a role such as VENDOR. Thus a wrong guess gives nothing that the Case Owner must then remove.
See also: CM-25-001 — context for the reader
CM-16-013 MAY The Evaluator's default role assignment MAY be overridden by actor-level configuration (e.g., a policy that maps known actor URIs to specific roles) or by the Case Owner at accept time when the Case Owner selects different roles for the suggested participant.

The Case Owner has ultimate authority over who participates in their case and in what role. The Evaluator's output is a suggested starting point to reduce friction, not a binding decision. The Case Owner can always update role assignments to whatever they determine is appropriate.
CM-16-014 MUST The Evaluator BT node assigned to default role list assignment MUST return FAILURE if it cannot produce a non-empty role list.

A FAILURE return forces the enclosing BT subtree to handle the empty-list case explicitly rather than propagating an empty list to downstream consumers.
CM-16-015 MUST NOT The downstream consumer node of the Evaluator BT node MUST NOT silently substitute a default for an empty list written by the Evaluator (ADR-0032 BT-HELPER-01).

Silent substitution by the consumer hides Evaluator failures and produces participants with unexpected role assignments.

Invitation Flow — Enrichment and Roles

ID Priority Requirement Related
CM-17-003 MUST The Invite activity MUST embed the intended case_roles: list[CVDRole] for the invitee so that EmitInviteActorToCaseNode can include them in the wire activity.

The CASE_MANAGER cannot route messages for a participant with no roles, or give it the correct access (CM-11-019). The participant record that the stub Invite creates (CM-11-026) gets its roles from the Invite. Thus the Invite must carry the roles that the Case Owner intended. These roles can come from a direct trigger request or from the suggest-actor round-trip.
Extends: CM-17-001
CM-17-006 MUST The CASE_MANAGER MUST commit exactly one CaseLedgerEntry for an Invite it emits, in the emitting tree, after it appends the Invite to the outbox.

The entry records an Invite that the CASE_MANAGER sent (SYNC-09-002, ADR-0119). If a send succeeds but its commit fails, the retry builds the Invite again under its first id. Thus the outbox does not queue it two times while it is pending (OX-06-002). If the Invite was delivered, it gets to its receiver again under the same id, and the receiver drops it (ID-02-001). The commit records the Invite one time.
Refines: SYNC-09-002
CM-17-015 MUST NOT The CASE_MANAGER MUST NOT address an Invite it emits to itself.

A copy addressed to the CASE_MANAGER would loop back to its own inbox, where a received-side path could record the same Invite a second time (ADR-0109).
Extends: CM-17-006
CM-17-016 MUST NOT A received-side path MUST NOT commit a second ledger entry for an Invite that the CASE_MANAGER emitted.

The commit in the emitting tree is the only commit for the Invite. A received-side commit of a loopback copy would record the same Invite a second time (ADR-0109).
Derives from: CM-17-006
CM-17-007 MUST This rule covers the direct-trigger path, where the Case Owner calls invite-actor-to-case with a roles list. In that path, SvcInviteActorToCaseUseCase MUST send the CASE_MANAGER the Case Owner's own recommend-actor Offer(Actor)[target=VulnerabilityCase], carrying those roles, from the Case Owner's identity and outbox.

The owner's direct invite is the recommend-actor flow with the recommender and the decider being the same participant, so it reuses that flow rather than adding a message type. This is one path for every topology: when the Case Owner's container also hosts the CASE_MANAGER the Offer loops back over HTTP (OX-12-001), and when it does not the Offer is the only way to reach the CASE_MANAGER without emitting in its name from a store that is not the ledger's home (ADR-0109).
CM-17-017 MUST NOT In the direct-trigger path, SvcInviteActorToCaseUseCase MUST NOT execute the invite tree locally as the CASE_MANAGER.

A local run would emit in the CASE_MANAGER's name from a store that is not the ledger's home (ADR-0109). The CASE_MANAGER emits the Invite on its own container, from the Offer it received.
Extends: CM-17-007
CM-17-018 MUST This rule covers an Offer(Actor)[target=VulnerabilityCase] whose recommender holds CVDRole.CASE_OWNER for the case. The CASE_MANAGER's recommend-actor received tree MUST emit the Invite directly with the offered roles, instead of forwarding the Offer to the Case Owner (CM-16-003, CM-16-004).

When the recommender is the Case Owner, the recommender and the decider are the same participant. Forwarding the Offer would ask the Case Owner a question it has already answered.
Extends: CM-17-007
Supersedes: CM-16-004
See also: CM-16-003 — context for the reader
CM-17-019 MUST The CASE_MANAGER's Invite for the Case Owner's direct invite MUST carry the offered roles, so its caseRoles is never empty (CM-17-003).

The roles travel in the Offer, and the CASE_MANAGER reads them from the received Offer it stored. That is the stored activity, not a value the trigger response carried, the same discipline CM-16-018 applies to the CASE_MANAGER's own outgoing Offer on Accept.
Extends: CM-17-018
Refines: CM-17-003
CM-17-008 MUST In the suggest-actor received path (the CASE_MANAGER receives Accept(Offer(CaseParticipant))), the invitee's CaseParticipant.case_roles MUST be populated when the CASE_MANAGER emits the stub Invite (CM-11-006), from the roles that Invite carries, originating from the Case Owner's Accept response (CM-16-006) or the CASE_MANAGER's default role assignment (CM-16-003).

In this path, AcceptOfferCaseParticipantReceivedUseCase does not write suggested_roles. The roles in the stub Invite are the roles that the Case Owner or the CASE_MANAGER's default assignment chose. The participant record is created with the Invite. Thus the Invite is the only source for its roles.
Extends: CM-11-006
See also: CM-16-003 — context for the reader
See also: CM-16-006 — context for the reader
CM-17-011 MUST When a stub carries the active embargo, this codebase MUST embed the whole EmbargoEvent as the inviter holds it, not just its ID and end_time.

This is a prototype decision, not a protocol decision. An implementation can let the invitee get the embargo from the inviter by its ID. This prototype does not supply that fetch. Thus the stub carries the full embargo. When the stub embeds the object as the inviter holds it, the stub keeps the sender's own start time and name. A copy built again from the ID and end time would not keep them.
Refines: CM-17-002 — CM-17-002 lets the stub carry the embargo inline or by ID; this codebase always carries it inline
CM-17-024 MUST NOT This codebase MUST NOT send a stub Invite whose active embargo the inviter cannot embed. It cannot embed it when it holds only the ID, or another embargo object.

A stub that names the embargo only by ID would give the invitee no method to read the terms, because this prototype supplies no fetch (CM-17-002). A stub that carried another embargo would state the wrong terms.
Derives from: CM-17-011
CM-17-012 MUST When the CASE_MANAGER receives Accept(Invite(VulnerabilityCase preview)[target=Actor]) from an invitee whose participant record is already joined, or removed, it MUST treat the Accept as a duplicate: it commits no ledger entry, changes no participant record or consent row, and sends no case snapshot, backfill or full-case Invite. A participant is joined when the case initialization sequence seated it or it has already accepted the stub Invite (CM-10-004). The test is the participant record alone, not any replication state the CASE_MANAGER holds for that participant.

When a joined participant accepts a stub Invite, the Accept is a redundant signal. Case creation seeds the participants that it seats as signatories (CM-14-003, CM-14-005). Thus the Accept changes nothing. The consent of a joined participant to a later embargo comes only from its answers to the Invite for that embargo. An Accept from a removed participant must not admit it again. Reinstatement is a separate act (CM-31-011). Replication state is not a correct test, because the embargo pause and ledger sync also write it.
Supersedes: CM-17-004
Refines: CLP-13-001
Uses definition from: CM-10-004

Participant Embargo Consent (per-embargo rows)

ID Priority Requirement Related
CM-18-017 MUST This codebase MUST raise when it reads a participant's missing consent row for a register entry, never reading it as a consent state (CM-18-021).

How this codebase treats the defect CM-18-021 names; split from CM-18-001 so that item states only the rows every participant holds (MS-12-010). Raising is how one implementation fails fast, and no other participant observes it.
Implements: CM-18-021
CM-18-005 MUST This codebase MUST change a participant's consent row only through one of three CaseParticipant methods. The method apply_pec_transition(embargo_id, trigger, entry_status=...) applies a PEC_Trigger, given the register status of the embargo's entry. The method copy_consent_row() writes a row that a ledger entry carries in full (ADR-0124). The method write_uninvited_rows() writes the UNINVITED rows that record no answer.

apply_pec_transition() validates the trigger against the consent table and the register status. It raises VultronInvalidStateTransitionError on an illegal transition or a frozen row. Thus consent writes fail closed, whatever the upstream BT guard coverage. A soft-fail write path would let a site skip an illegal transition and nobody would see it. Thus apply_pec_transition_if_legal() is the only place where an illegal trigger is a recorded no-op. Per ADR-0048, ADR-0122, ADR-0124.
Implements: CM-18-003
CM-18-024 MUST Code that changes a consent row through CaseParticipant.apply_pec_transition() MUST then persist the participant.

The transition changes the row on the participant object in memory only. A caller that does not persist the participant loses the change, and the next reader sees the old row.
Extends: CM-18-005
CM-18-025 MUST This codebase MUST call CaseParticipant.copy_consent_row() only from apply_embargo_change(), after that function checks the row's starting state against the consent row machine (CM-18-003) and the RSVP deadline rule (CM-28-013).

The copy write takes a row as a ledger entry carries it and does not consult the consent table. It stays fail-closed only because its one caller first checks that the row starts where the entry implies. A Create finds no row yet, and carries an UNINVITED row or one that one consent row trigger moves from UNINVITED. An Update finds a held row that one consent row trigger moves to the carried row (CM-18-003), or an INVITED row that gets a fresh RSVP deadline (CM-28-013, ADR-0124).
Extends: CM-18-005
Uses definition from: CM-18-003
Uses definition from: CM-28-013
CM-18-026 MUST NOT Code MUST NOT assign CaseParticipant.embargo_consents directly to record a consent change.

A direct assignment to the rows skips the consent table, so a row could get a state that no trigger leads to (CM-18-003).
Derives from: CM-18-005
CM-18-006 MUST A protocol-significant consent change MUST be reproducible on every replica from the canonical case ledger: it is applied by the same EmbargoLifecycle operation on the CASE_MANAGER after it commits the entry of the activity that caused it (the relayed Invite, the Accept or Reject, the expiry, the late-Accept honour), and by replay of that entry on each replica. The consent rows are not carried in any ParticipantStatus snapshot.

Consent lives on the CaseParticipant rows, not on ParticipantStatus, so an Add(ParticipantStatus) entry carries no consent. The ledger entry of the causing activity is the record, and replaying it through the lifecycle operation gives every store the same rows. Per ADR-0048, ADR-0122.
CM-18-007 MUST The case-initialization sequence MUST establish the default embargo before seeding each participant's consent row for it, so that the participant record written at initialization carries its true post-initialization rows.

AGREE is valid directly from UNINVITED (CM-18-003, ADR-0048). Thus an initialization participant gets its consent in one transition. The record written at initialization can then carry its true rows, and no placeholder is necessary. A placeholder entry and then a corrective entry would move every downstream log_index. Replicas that wait for an entry by its log_index would then apply later changes at the wrong time. One entry for each participant at initialization keeps log_index order stable. It also keeps the ADR-0079 property that log_index order is causal order (CLP-14-001).
CM-18-009 MUST Any consent trigger not listed in CM-18-003 MUST be rejected as a protocol error.

Rejecting unlisted transitions fail-closes the consent table, preventing consent corruption from malformed or unexpected triggers.
Implements: CM-18-003
CM-18-012 MUST The case initialization sequence MUST commit exactly one add_participant_status_to_participant ledger entry per participant, never a placeholder entry followed by a corrective entry.

Two entries for each participant would move every downstream log_index. Replicas that wait for an entry by its log_index would then apply later changes at the wrong time. One entry for each participant keeps log_index order stable. AGREE is valid directly from UNINVITED (CM-18-003, ADR-0048). Thus an initialization participant gets its consent in one transition, and a placeholder is not necessary.
Depends on: CM-18-007
CM-18-016 MUST NOT The embargo lifecycle MUST NOT write a consent row to record a lapse or an exit. Beyond the UNINVITED row a proposal writes for every participant (CM-18-001), a proposal, the activation of a longer revision and the termination of the embargo change no row of a participant that has not itself been invited, has not itself answered, is not the Case Owner activating the embargo, or whose agreement is not being carried over by containment (EP-05-003); a participant's lapsed or exited position is read from its rows and the register (CM-18-001).

A reader gets a lapse or an exit from the rows and the register (CM-18-001). A row written to record a lapse or an exit would be a second record of consent next to the rows. That record could disagree with the rows, and ADR-0122 does not allow this. Reconciliation writes at activation or termination would have nothing to keep in step. One row for each embargo already gives all the information that those writes would give.
Refines: CM-18-001
See also: EP-05-003 — context for the reader

Participant Index Discipline

ID Priority Requirement Related
CM-19-001 MUST case_participants (the persisted set of CaseParticipant records) is the authoritative source of participant membership. actor_participant_index (the in-memory dict mapping actor IDs to participants) is a cache derived from it. Divergence between these two structures is a hard error, not a recoverable state.

A divergence means the cache has entries the authority doesn't know about (or vice versa), producing silently incorrect routing and access-control decisions.
CM-19-002 MUST Each code path that adds, removes or updates case_participants MUST update actor_participant_index atomically, in the same transaction or method call, never later.

Lookups by actor use actor_participant_index (CM-19-003). If the index lags case_participants, a sender check or a role check can get a participant that the authority does not hold, or get no participant for one that it holds. CM-19-001 makes that difference a hard error. The only way to prevent it is that every write to the set updates the index in the same step.
Implements: CM-19-001
CM-19-003 MUST Code that needs a participant by actor ID MUST read it from actor_participant_index, the cache.

The index gives a fast lookup of the participant for one actor. It comes from case_participants and holds one participant id per actor, so it answers a lookup by actor without a scan of the records.
Uses definition from: CM-19-001
CM-19-004 MUST Code that needs the canonical participant set, as for broadcast or audit, MUST read case_participants, never actor_participant_index.

The index holds one participant id per actor, so it is not the set of records, and its population order is undefined. Broadcast and audit must cover every participant record in a reproducible order. Only the authoritative set gives that order (CM-19-001).
Uses definition from: CM-19-001

Ownership Transfer Protocol Effects

ID Priority Requirement Related
CM-21-004 MUST This codebase MUST commit the three writes of an ownership transfer to storage as one atomic transaction, rolled back whole when any part fails. They are the strip of CVDRole.CASE_OWNER from the previous holder (CM-21-003), the attributed_to update (CM-21-024) and the role's grant to the new holder (CM-21-002).

Without atomicity a crash or exception between the strip and the grant produces a case with zero CASE_OWNER holders — a state worse than two simultaneous holders because it cannot be recovered by any subsequent normal protocol message. The invariant in CM-21-001 ("at most one at any point in time") logically implies that the case MUST have exactly one CASE_OWNER at all times; this spec makes the storage-transaction requirement explicit so that DataLayer implementations cannot satisfy CM-21-001 through sequential saves.
Implements: CM-21-001
Uses definition from: CM-21-002
Uses definition from: CM-21-003
Uses definition from: CM-21-024
CM-21-042 MUST The wire layer MUST normalise an ownership-transfer Offer's end_time to UTC at the wire edge (CS-13-001, ADR-0032).

The deadline is compared with the CASE_MANAGER's clock. A time with an offset, or none, compared without normalising could move the deadline by hours.
Refines: CS-13-001
Refines: CS-13-009

RM Case Closure via Leave(VulnerabilityCase)

Requirements for the canonical RM case closure path: Leave(VulnerabilityCase) is the sole mechanism for advancing a participant's RM state to CLOSED. An Add(ParticipantStatus) whose status carries rmState=CLOSED is not a valid closure trigger. See ADR-0050 (Leave is canonical for RM closure) and ADR-0051 (CASE_MANAGER RM lifecycle). Decided: the maintainer decided the closure semantics in CM-23-002, CM-23-013 and CM-23-014 (what the owner's close does to pending Invites and to later Leaves) on 2026-10-12. ADR-0085 sets the owner-close write boundary. ADR-0131 sets the CM-23-013 reply to late traffic: by default it is dropped, and only a late Leave may get an as:Reject (#4065). The CM-23-014 settle step is #4066 (PR #4489).

ID Priority Requirement Related
CM-23-028 MUST Every check of the owner-close write boundary (CM-23-002) in this codebase MUST use one shared predicate, keyed on the CASE_MANAGER's own RM.CLOSED status entry.

If each check computed the boundary for itself, two checks could disagree on whether a case is fully closed. Then one path could refuse an act that another path records. The predicate lives in vultron/core/predicates/case_closure.py.
Uses definition from: CM-23-002
CM-23-017 MUST The reference CASE_MANAGER MUST choose its CM-23-040 reply at one configuration point, ActorConfig.post_close_reply, whose default is drop.

A Reject that wraps most activities already carries a protocol meaning for its recipient: Reject(Invite) is a declined invitation and Reject(Offer(...)) a declined offer, so a reply to a late Invite or Offer would be misread as a decision. Refuse(Leave(VulnerabilityCase)) already means "close refused" (CM-23-011) and cannot be misread. Dropping is the default because it is what an exited process does, and CM-23-041 already tells participants not to rely on a reply.
Refines: CM-23-040
CM-23-056 MUST With post_close_reply set to drop, the reference CASE_MANAGER MUST send nothing for a late activity. A late activity is one that arrives for the case after it is fully closed (CM-23-013).

Dropping is what an exited process does, and CM-23-041 already tells participants not to rely on a reply.
Extends: CM-23-017
Uses definition from: CM-23-013
CM-23-057 MUST With post_close_reply set to refuse, the reference CASE_MANAGER MUST answer a late Leave(VulnerabilityCase) with the refusal notice, a Refuse of the Leave as received (CLP-05-001).

A Refuse(Leave(VulnerabilityCase)) already means "close refused" (CM-23-011), so the leaver cannot misread it as a decision on anything else, and it reads it as every other refusal notice (CLP-05-007, ADR-0196).
Extends: CM-23-017
Uses definition from: CLP-05-001
CM-23-045 MUST Under both post_close_reply settings, the reference CASE_MANAGER MUST drop with no reply every late activity other than a Leave(VulnerabilityCase) (CM-23-017). A Create(CaseProposal) names a report, not a case, so it is not a late activity (ADR-0131). One that resolves to a fully closed case gets a Reject(CaseProposal) under both settings (CP-05-014, CP-05-018).

A Reject of any other late activity would be misread as a decision on it, such as a declined invitation or a declined offer (CM-23-017). A late activity here is one for the case, as in CM-23-013. A Reject(CaseProposal) is a decision on the proposal, so it cannot be misread, and the proposer learns that it must not wait for a case.
Extends: CM-23-017
See also: CP-05-014 — context for the reader
See also: CP-05-018 — context for the reader
CM-23-046 MUST The reference CASE_MANAGER MUST report every late activity as REFUSED, under both post_close_reply settings.

The verdict tells the inbox that nothing was applied, whether or not a Reject was sent. If a reply setting changed the verdict, the same late activity would read as applied under one setting and refused under the other.
Extends: CM-23-017
CM-23-047 MUST On dropping a late activity, the reference CASE_MANAGER MUST log it at INFO with the activity id, the sender's actor id and the case id.

A drop sends nothing, so the log line is the only record that the activity arrived and was dropped. An operator needs the ids to find the activity and the case (SL-01).
Extends: CM-23-017
CM-23-020 MUST In this codebase the ACTIVE_PARTICIPANT sender standing (HP-01-009) MUST mean an active participant (CM-10-004) whose closure the case's ledger does not record.

How this codebase's sender guards meet CM-23-018; split from it so CM-23-018 states only what a closed sender is refused and sent (MS-12-010). Sender standings and guard composition are this codebase's mechanism (HP-01-007).
Implements: CM-23-018
Uses definition from: HP-01-009
Uses definition from: CM-10-004
CM-23-054 MUST Every guard that enforces the ACTIVE_PARTICIPANT standing (CM-23-020) MUST ask one shared predicate (HP-01-007).

If guards each checked the standing in their own way, two use cases could disagree on whether one sender may act. One predicate gives every guard the same answer.
Extends: CM-23-020
See also: HP-01-007 — context for the reader
CM-23-055 MUST NOT The Reject(CaseLedgerEntry) use case MUST NOT declare the ACTIVE_PARTICIPANT standing, keeping the active check of SYNC-03-005 as its guard.

A closed sender's resync request must reach the closure-entry replay that CM-23-048 requires. The ACTIVE_PARTICIPANT standing refuses a closed sender, so declaring it would refuse that request.
Extends: CM-23-020
Uses definition from: SYNC-03-005

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-005 MUST Every path that emits an Activity on another participant's behalf MUST obtain the Activity's actor, attributed_to and in_reply_to from one shared helper, except where another rule fixes in_reply_to itself (CM-11-044, CM-33-017). Such a path is a trigger use case, or a received-side tree performing the CM-24-010 delegated emit.

If each call site builds the actor, attributed_to and in_reply_to values again, they can become different at different sites. A wrong value attributes the act to the wrong actor, names the wrong request, or makes the act fail authentication (CM-24-001, CM-24-002, CM-24-020). The received-side relay is also a delegated emit (CM-24-010).
Uses definition from: CM-24-010
See also: CM-11-044 — a replacement stub Invite names the Invite it supersedes, not the request
See also: CM-33-017 — the role-offer forward names the recorded Offer even when self-asked
CM-24-012 MUST The shared delegated-authorship helper (CM-24-005) MUST set actor to the actor doing what was asked, attributed_to to the actor that asked, and in_reply_to to the request the doer received. The doer is the CASE_MANAGER executing the gated tree. The asker is the trigger's requesting actor, or the sender of the activity the received tree acts on, and the request is that activity.

None of the values needs a calculation, because the emit point knows the doer, the requester and the request. The CASE_MANAGER is the actor that receivers authenticate (CM-24-001), attributed_to recovers who asked (CM-24-002), and in_reply_to names what the act answers (VOC inReplyTo). A distinct asker reaches the CASE_MANAGER only by message (ADR-0109), so a delegated act with no request to name is a programming error (ADR-0199).
Extends: CM-24-005
CM-24-013 MUST The shared delegated-authorship helper (CM-24-005) MUST live in a module that both use cases and BT nodes may import (BTND-04-003).

The received side builds delegated emits in BT nodes, and the trigger side in use cases. If BT nodes could not import the helper, the received side would have to build the pattern again by hand.
Extends: CM-24-005
Derives from: BTND-04-003
CM-24-008 MUST NOT A trigger, received tree or shared helper in this codebase MUST NOT carry an arm for a case with no CASE_MANAGER (CM-24-014).

How this codebase keeps CM-24-014 from being bypassed; kept apart from the protocol rules that a case always has a CASE_MANAGER (CM-02-014) and that no activity goes around it (CM-24-014), as MS-12-010 directs. Trees, helpers and resolvers are this codebase's structure.
Implements: CM-24-014
CM-24-015 MUST A resolver in this codebase that finds no CASE_MANAGER for a case MUST fail, never succeeding with a warning.

A success with a warning lets the caller go on as if a CASE_MANAGER were found, which is the arm CM-24-008 forbids. A failure stops the act, as CM-24-014 requires.
Extends: CM-24-008
CM-24-022 MUST The shared delegated-authorship helper (CM-24-005) MUST raise when the asker differs from the doer and the caller names no request.

A delegated act with no request to name is a programming error, so the helper fails it as a wiring fault before any activity is built (CM-24-020, ADR-0109).
Extends: CM-24-012
See also: CM-24-005 — names the shared helper the rule applies to

Embargo Invite RSVP Deadlines

Requirements for the optional RSVP-by deadline carried on an embargo invitation, the authority relationship between that wire value and the CM-18-023 pocket-veto policy window, and how an expiry is recorded. Codified by ADR-0065. Source: IDEA-2066.

ID Priority Requirement Related
CM-28-006 MUST This codebase MUST normalise an inbound Invite.end_time to UTC before it compares the value with the current time (CS-13-009).

A deadline compared in the wrong timezone lapses at the wrong instant, breaking the bilateral determinism CM-28-002 exists to provide. ADR-0032's edge normalisation (naive → UTC) prevents this without per-field guarding in the extractor. See CS-13-001 through CS-13-005 and ADR-0065.
Extends: CS-13-009
CM-28-021 MUST This codebase MUST normalise a naive (not timezone-aware) Invite.end_time to UTC at the wire edge (ADR-0032).

Normalising at the edge means every downstream comparison is against a timezone-aware value, with no per-field guard in the extractor. A naive value that reached core would compare in the wrong timezone and lapse at the wrong instant (CM-28-002).
Implements: CM-28-006
CM-28-007 MUST Embargo invite expiry MUST be evaluated lazily: expiry is derived from (end_time, now) whenever a participant's consent rows are read or an inbound Accept/Reject for the invitation is processed.

Lazy derivation from an explicit deadline is deterministic and requires no new infrastructure. No scheduler exists in production, and the Sentinel invocation model remains an open question (notes/coordination-agents.md). See ADR-0065.
Extends: CM-28-003
CM-28-008 MUST NOT Implementations MUST NOT require a scheduler or Sentinel runtime for embargo invite expiry correctness.

No scheduler exists in production; making correctness depend on one would render conformance impossible without new infrastructure. The Sentinel is an optional accelerator only. See ADR-0065.
Derives from: CM-28-007
CM-28-010 MUST NOT The expiry-versus-refusal provenance MUST NOT be duplicated onto a consent row as a reason field.

A reason discriminator on a consent row — which holds only the embargo id and the state — would be a second source of truth able to drift from the ledger. The canonical ledger is the sole record of provenance (ADR-0019). See ADR-0065.
Constrains: CM-28-005
CM-28-016 MUST In this codebase the CASE_MANAGER role gate (BT-17-001) MUST guard the CASE_MANAGER's commit of the invite-expiry Update(EmbargoConsent) (CM-28-014).

How this codebase keeps the expiry entry the CASE_MANAGER's alone; split from CM-28-014 so CM-28-014 states only who records an expiry and what replicas learn from it (MS-12-010).
Implements: CM-28-014
Refines: BT-17-001
CM-28-030 MUST In this codebase a replica MUST apply the invite-expiry Update(EmbargoConsent) entry (CM-28-014) through the consent slot of create_add_log_entry_tree (RSH-08-004).

How this codebase copies the CASE_MANAGER's expiry entry onto replicas. One slot applies every consent entry, so a replica reads TIMED_OUT only from the entry and never computes an expiry itself.
Implements: CM-28-014
Refines: RSH-08-004
CM-28-015 MUST The CASE_MANAGER MUST sweep a case's overdue invitations before it commits the Case Owner's decision on an embargo proposal (MSM-07-008, MSM-07-009). A sweep expires each INVITED consent row past its RSVP deadline whose embargo register entry is an open proposal or the embargo in force. It expires each such row through its CM-28-009 Update(EmbargoConsent) and TIME_OUT.

Without a sweep, the CASE_MANAGER checks expiry only on a late Accept and when the Case Owner closes (CM-23-014). An invitee that never answers is then never recorded as timed out. The Case Owner then decides without knowledge of the timeout (EP-09-006, MSM-07-007). Embargo activities read the consent rows (CM-28-007), so a sweep at that point keeps expiry lazy (CM-28-008).
Refines: CM-28-007
Uses definition from: CM-28-009
Uses definition from: MSM-07-008
Uses definition from: MSM-07-009
CM-28-025 MUST NOT The CASE_MANAGER MUST NOT sweep a consent row of a replaced, rejected, cancelled or ended embargo.

Such a row is frozen: an answer to a version that no longer stands can change nothing (CM-18-005). Expiring it would record a lapse on an invitation whose embargo is already gone.
Extends: CM-28-015
CM-28-026 MUST The CASE_MANAGER MUST run the CM-28-015 sweep only after the door guards admit the activity, its sender gate (HP-01-006) included.

The sweep is a clock decision (CLP-10-025, ADR-0214). Running it after the door guards means a sender with no standing makes the CASE_MANAGER write nothing.
Extends: CM-28-015
Uses definition from: HP-01-006
CM-28-027 MUST The CASE_MANAGER MUST run the CM-28-015 sweep before the activity's own refusals (MSM-07-008). Examples are an embargo that is not an open proposal, or a public, exploited or attacked CS.

An overdue row is a fact from the CASE_MANAGER's clock, not evidence from the activity. Sweeping before the activity's own refusals records the expiries even when the activity is then refused (ADR-0214).
Extends: CM-28-015
Uses definition from: MSM-07-008
CM-28-028 MUST The CASE_MANAGER MUST also run the CM-28-015 sweep whenever it processes any other received embargo activity for the case.

Embargo activities read the consent rows (CM-28-007), so a sweep at each one keeps expiry lazy (CM-28-008). Without it, an invitee that never answers is recorded as timed out only on a late Accept or at closure (CM-23-014).
Extends: CM-28-015
CM-28-029 MUST The CASE_MANAGER MUST also run the CM-28-015 sweep in every embargo trigger that the actor holding CVDRole.CASE_MANAGER runs, the Case Owner's own trigger included (EP-09-008).

The Case Owner's own decision trigger can run on the actor that holds the CASE_MANAGER role. If a trigger skipped the sweep, the owner would decide without knowing which invitations timed out (EP-09-006, MSM-07-007).
Extends: CM-28-015
See also: EP-09-008 — context for the reader

Case Collection Mutation Discipline

Requirements governing post-construction mutation of the case collections whose items exist in incompatible wire and core shapes. validate_assignment does not cover in-place mutation — list.append is not an attribute assignment, so Pydantic never observes it — so these collections need a separate prohibition. Codified by ADR-0064. Source: CONCERN-2261.

ID Priority Requirement Related
CM-27-001 MUST NOT Core code under vultron/core/ MUST NOT change case_participants or case_statuses on a VulnerabilityCase after construction except through its canonical mutators. Direct writes such as case.case_participants.append(...) and case.case_statuses = [...] are what it rules out. The mutator methods themselves, in vultron/core/models/case/, are exempt.

A wire-shaped participant or status in a list of core types does not cause an error when code reads it. It reads as absent, and readers use an initial state in its place. This silently resets the case's state. validate_assignment cannot prevent this, because append is not an assignment. Thus the only guard is to send every change through a mutator that validates. PRM-03-001 gives the same prohibition for case_roles.
CM-27-002 MUST Passing case_participants=[...] or case_statuses=[...] as a constructor argument when creating a VulnerabilityCase is permitted and does not violate CM-27-001; the prohibition applies only to post-construction mutation.

Constructor arguments are validated, which is precisely the guarantee CM-27-001 exists to restore. This clarification prevents over-application of the rule, mirroring PRM-03-002.
Refines: CM-27-001
CM-27-003 MUST VulnerabilityCase MUST expose a canonical mutator for appending a case status, so that CM-27-001 can be satisfied without direct list mutation. add_participant() already provides this for case_participants; removal keeps the record on the roster (CM-31-001), so the roster has no deleting mutator.

A prohibition with no permitted alternative cannot be implemented. Without a status mutator, code that records a new case status must append to case_statuses directly, which CM-27-001 forbids. add_case_status() on VulnerabilityCase is that mutator.
Implements: CM-27-001
See also: CM-31-001 — context for the reader

Case Status Recency Resolution

Rules for determining which CaseStatus snapshot is current when multiple snapshots exist in the case_statuses history, and how their times follow that order.

ID Priority Requirement Related
CM-29-001 MUST VulnerabilityCase.current_status MUST return the CaseStatus appended last to the case's case_statuses.

Every case status is the CASE_MANAGER's: it seeds the first at creation and builds each later one from the current one, so each append is a valid next step. A replica appends in ledger order (CLP-14-001), so append order is the CASE_MANAGER's commit order everywhere. A timestamp rule would read a clock instead: one that steps back, or a CASE_MANAGER role delegated to an actor on another clock (CM-02-014), could make an older status current.
Refines: SM-05-002
CM-29-006 MUST A CaseStatus this codebase authors MUST carry an updated equal to its published, or no updated.

A committed case status never changes: a new state is a new status (SM-05-001), and the EM stamp replaces the current status with a copy that keeps its times (ADR-0122). So published is its one time, and an updated that differs from it would claim a change that never happened.
CM-29-008 MUST When a replica appends a ledgered CaseStatus whose published is not later than that of the status before it, it MUST log a WARNING naming both statuses and the case.

The CASE_MANAGER broke CM-29-005, and the replica accepts the status anyway (CM-29-007). The log is the only record that the fault happened.
Extends: CM-29-007

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-014 MUST This codebase MUST NOT store a case's activeParticipants collection (CM-31-003): it is computed from the participant records whenever the case is serialized.

How this codebase keeps CM-31-003's collection from drifting from the participant records; split from it so CM-31-003 states only what the case carries on the wire and what a receiver does with it (MS-12-010).
Implements: CM-31-003

CaseProposal Protocol

Requirements for the CaseProposal protocol flow, which separates the act of requesting case initialization from the act of creating the case. Covers the wire vocabulary type, the Create/Accept/Reject message flow, and the corresponding MessageSemantics values and received-side use cases.

File ID: CP

Wire Vocabulary

ID Priority Requirement Related
CP-01-001 MUST The wire layer MUST define an as_CaseProposal object type that extends as_VultronObject.

A dedicated object type enables pattern-discriminated routing in the semantic extractor and preserves AS2 semantics by separating the proposal object from the eventual VulnerabilityCase.
CP-01-002 MUST as_CaseProposal MUST include an id_ field containing a full URI that uniquely identifies the proposal.

Every later message about the proposal names it by this id: the Accept or Reject that answers it, the duplicate check (CP-05-006) and the sender check (CP-05-010). A full URI names one object across all actors, so proposals from different proposers do not share a key by accident. CP-05-010 refuses a sender that reuses another proposer's identifier.
CP-01-003 MUST as_CaseProposal MUST include an attributed_to field identifying the report receiver that originated the proposal (the proposer, who becomes the CASE_OWNER if the proposal is accepted).

The CASE_MANAGER seats the actor this field names as the Case Owner of the new case (CP-09-001), and it checks that the actor of the Create names the same actor (CP-01-015). Without the field, the case would have no owner to record.
CP-01-004 MUST as_CaseProposal MUST include an object_ field containing a fully inline as_VulnerabilityReport around which the case is to be created. URI references to the report are NOT permitted (see AKM-03-003).

The case-actor service needs the vulnerability report to initialize the case. URI references are prohibited because the receiver may not have the referenced object, and this codebase fetches only the objects the note on AKM-05-007 lists (AKM-03-003).
See also: AKM-03-003 — context for the reader
CP-01-005 MUST as_CaseProposal MUST include a target field containing the URI of the prospective case-actor service to which the proposal is addressed.

A proposal is a request to one service. The target records in the proposal itself which service the report receiver asked to create the case, so the request names its addressee wherever it is stored or read, not only in the delivery's to.
CP-01-007 MUST When the proposing actor knows which Offer(VulnerabilityReport) brought it the report, it MUST carry that provenance on the as_CaseProposal as offerId and offerActorId.

The canonical add_report_to_case entry records which Offer brought the report into the case, so every replica and every auditor of the ledger can trace the report to its submission (SYNC-02-002). The case-actor cannot supply that provenance from storage: the OfferRecord belongs to the actor that received the Offer, and a co-located case-actor has its own store with no read into a sibling's (PCR-01-003, DL-07-005). So it travels on the proposal for the same reason and by the same rule as the report itself (CP-01-004). A participant that joined through an Invite does not use it to answer the Offer, which was never sent to it (CM-11-018).
CP-01-019 MUST If its own store holds no OfferRecord for the report, the case-actor MUST take the offerId of its canonical add_report_to_case entry from the proposal (CP-01-007).

The OfferRecord belongs to the actor that received the Offer, and a co-located case-actor cannot read a sibling's store (PCR-01-005, DL-07-005). Without the provenance the proposal carries, the canonical entry could not name the Offer that brought the report into the case (SYNC-02-002).
Uses definition from: CP-01-007
CP-01-008 MUST When the proposing actor holds the Offer(VulnerabilityReport) that brought it the report, it MUST carry that Offer whole and inline as the proposal's inReplyTo.

The case-actor has never seen the Offer, and a sender inlines the objects it introduces (ADR-0107); the bare offerId of CP-01-007 lets the case-actor name the submission but not read it. Carrying the Offer whole is what lets the Reporter's terms arrive as the Reporter stated them — the same activity the report receiver received, not the receiver's paraphrase of one field — and it is the only path by which EP-04-003's shortest-wins comparison at case creation ever gets a sender candidate. inReplyTo is AS2's own name for the relationship: the proposal answers the report submission.
Extends: CP-01-007
CP-01-020 MUST An as_CaseProposal that carries both inReplyTo and the bare provenance of CP-01-007 MUST name the same Offer in both.

Two names for the submission that disagree leave the case-actor no way to tell which Offer brought the report. The ledger entry would record one Offer while the terms came from another.
Extends: CP-01-008
Uses definition from: CP-01-007
CP-01-021 MUST The case-actor MUST read the Reporter's proposed embargo terms (EP-04-004) only from the Offer in the proposal's inReplyTo, or, when that Offer proposes none, from the CSAF disclosure date its proposer copied from that Offer's report, never fetching or reconstructing them elsewhere.

The carried Offer is the activity the report receiver received, so the terms arrive as the Reporter stated them. A disclosure date the proposer copies as the document states it is still the Reporter's own value, since the proposer passes it along without judging it. Terms rebuilt from another source would be the receiver's paraphrase, and a fetch would need an object the case-actor has never seen.
Uses definition from: CP-01-008
Uses definition from: EP-04-004
CP-01-010 MUST In this implementation, a sender MUST carry the proposing actor's full actor profile inline as the actor of Create(CaseProposal), carrying its embargo policy when it has published one.

A sender inlines the objects it introduces, as CP-01-008 does the Reporter's terms (ADR-0107), so a receiver that already supports dereference still needs no fetch for a proposal this codebase sends.
Refines: CP-01-009
CP-01-014 MUST In this implementation, the CASE_MANAGER MUST accept as the actor of Create(CaseProposal) the proposer's inline profile or its id, which it dereferences from the proposer's published profile before processing the proposal (AKM-05-007).

A receiver dereferences the reference CP-01-009 allows (AKM-05-003), so a sender that names its proposer by id is not refused for it.
Refines: CP-01-009
Refines: AKM-05-007
CP-01-015 MUST The CASE_MANAGER MUST refuse at the parse edge, with a reason naming the fault, a Create(CaseProposal) whose actor is a Link or does not name the proposal's attributed_to.

The proposer's profile supplies the CASE_OWNER's actor default, so a profile that is not the proposer's would let another actor's terms bind the case.
Extends: CP-01-014
CP-01-016 MUST The CASE_MANAGER MUST read the CASE_OWNER's actor default only from the inline or fetched proposer profile, never from its own store. A profile with no embargo policy means the CASE_OWNER has no actor default.

The profile the proposal carries or names is the one the owner published for this proposal; a record in the CASE_MANAGER's store may be stale or someone else's.
Extends: CP-01-014
CP-01-017 MUST The CASE_MANAGER MUST NOT store a fetched proposer profile, or retain an inline or fetched one as a candidate for any other case.

A policy read from one proposal reflects that profile as sent; keeping it for later cases would let a stale policy win shortest-wins.
Extends: CP-01-016
CP-01-018 MUST The CASE_MANAGER MUST refuse a proposal whose proposer profile could not be fetched (AKM-05-015).

Refusing a profile it cannot fetch, rather than creating the case without an actor default, keeps the owner's published terms from being silently dropped.
Extends: CP-01-014
Refines: AKM-05-015
CP-01-013 MUST In this implementation, the roles a report receiver states in proposerCaseRoles (CP-01-011, CP-09-007) MUST be copied from its own ActorConfig.default_case_roles (CFG-07-002).

The receiver's configuration is the one place this codebase records the roles an actor holds in the cases it owns, so a proposal copied from anywhere else would seat the owner with roles its operator never configured. The CASE_MANAGER cannot read that configuration (ADR-0073), so the copy has to happen on the sender's side.
Implements: CP-01-011
Uses definition from: CFG-07-002
See also: CP-09-007 — the sender's source of roles is not how the CASE_MANAGER seats only the stated roles

MessageSemantics Values

ID Priority Requirement Related
CP-02-001 MUST The MessageSemantics enum MUST include CREATE_CASE_PROPOSAL for the pattern Create(CaseProposal).

The dispatcher sends each received activity to one use case by its MessageSemantics value. Without a value for Create(CaseProposal), a received proposal has no use case to handle it.
CP-02-002 MUST The MessageSemantics enum MUST include ACCEPT_CASE_PROPOSAL for the pattern Accept(CaseProposal).

The dispatcher sends each received activity to one use case by its MessageSemantics value. Without a value for Accept(CaseProposal), the report receiver cannot record that its proposal was accepted.
CP-02-003 MUST The MessageSemantics enum MUST include REJECT_CASE_PROPOSAL for the pattern Reject(CaseProposal).

The dispatcher sends each received activity to one use case by its MessageSemantics value. Without a value for Reject(CaseProposal), the report receiver cannot record that its proposal was rejected.

Extractor Patterns

ID Priority Requirement Related
CP-03-001 MUST SEMANTIC_REGISTRY MUST contain a pattern entry for (Create, as_CaseProposal) -> CREATE_CASE_PROPOSAL.

Semantic extraction finds the MessageSemantics of a received activity from the patterns in SEMANTIC_REGISTRY. With no entry for (Create, as_CaseProposal), the activity is not classified as part of the proposal flow and reaches none of its use cases.
CP-03-002 MUST SEMANTIC_REGISTRY MUST contain a pattern entry for (Accept, as_CaseProposal) -> ACCEPT_CASE_PROPOSAL.

Semantic extraction finds the MessageSemantics of a received activity from the patterns in SEMANTIC_REGISTRY. With no entry for (Accept, as_CaseProposal), the activity is not classified as part of the proposal flow and reaches none of its use cases.
CP-03-003 MUST SEMANTIC_REGISTRY MUST contain a pattern entry for (Reject, as_CaseProposal) -> REJECT_CASE_PROPOSAL.

Semantic extraction finds the MessageSemantics of a received activity from the patterns in SEMANTIC_REGISTRY. With no entry for (Reject, as_CaseProposal), the activity is not classified as part of the proposal flow and reaches none of its use cases.
CP-03-004 MUST All three CaseProposal extractor patterns MUST appear before any more-general patterns that could match the same activity types (e.g., generic Accept or Reject catch-all entries), to prevent misrouting (per SE-03-002).

The registry is ordered from the most specific pattern to the least specific (SE-03-002), and extraction uses the first pattern that matches. A general Accept or Reject pattern placed first would match the answer to a proposal, and the report receiver would handle it as a different message.
Refines: SE-03-002

Protocol Flow — Sending

ID Priority Requirement Related
CP-04-002 MUST This codebase MUST send Create(CaseProposal) from a distinct BT node, ProposeReportCaseToActorNode, separate from EnsureCaseActorHostedNode.

Conflating actor registration with proposal sending violates single responsibility and causes the proposal to be sent before the case-actor service is ready. See notes/case-proposal.md for the pitfall.
CP-04-006 MUST NOT EnsureCaseActorHostedNode MUST NOT send a CaseProposal activity, or take any step beyond making the case-actor a hosted actor.

A node that both hosts the case-actor and proposes the case can send the proposal before the case-actor service is ready to receive it. Keeping the hosting node to its one job leaves the proposal to the node that runs after it.
Extends: CP-04-002
CP-04-005 MUST In this implementation, the case-actor service's actor identity (CP-04-003) MUST be {case_actor_service_url}/actors/case-actor, built from the sender's configured ActorConfig.case_actor_service_url, one identity per case-actor container.

A sender can address the service only if it can compute the identity from what it already knows, and the configured base URL is the one thing every actor of this deployment is given about the service. A fixed path under it lets the container register that identity once, at seed time.
Implements: CP-04-003
CP-04-004 MUST Whatever provisions the case-actor's record MUST write it into the case-actor's own store, since the inbox route resolves an actor from the store its URI names. A copy in the sending actor's store does not make the case-actor addressable.

Each actor has its own store (ADR-0073), and the inbox route finds an actor in the store its URI names. A record in the case-actor's own store makes it an actor that can receive messages. A record in the sender's store only says that the sender knows of a peer. If only the sender's record exists, the inbox answers 404 Actor not found and the proposal is not delivered.
Derives from: DL-07-001

Protocol Flow — Receiving (Case-Actor Side)

ID Priority Requirement Related
CP-05-001 MUST A CreateCaseProposalReceivedUseCase MUST be implemented on the case-actor side to handle incoming Create(CaseProposal) activities.

The Case Actor Service must answer each proposal it admits (CP-05-002). The dispatcher sends each Create(CaseProposal) to this use case, so without it a proposal reaches no code that can answer it.
CP-05-009 MUST This codebase MUST carry the as_CaseProposal inline as the object_ of the Accept(CaseProposal) of CP-05-003 and of the Reject(CaseProposal) of CP-05-004.

CP-05-003 and CP-05-004 allow the proposal inline or by reference; this item states how this codebase meets them (MS-12-010). The report receiver reads the report from the proposal in the answer to find its pending request (CP-06-003), and this codebase fetches only the objects the note on AKM-05-007 lists. So the proposal travels inline and stays inline through the outbox store. This is a prototype choice, not a protocol rule.
Implements: CP-05-003
Implements: CP-05-004
CP-05-021 MUST This codebase MUST keep the inline as_CaseProposal of CP-05-009 inline through the outbox store round-trip, never dehydrating it to a bare URI.

The report receiver reads the report from the proposal in the answer (CP-06-003). An answer that leaves the outbox store with a bare URI where the proposal was gives the receiver nothing to read, because this codebase does not fetch it.
Extends: CP-05-009

Protocol Flow — Receiving (Report-Receiver Side)

ID Priority Requirement Related
CP-06-001 MUST An AcceptCaseProposalReceivedUseCase MUST be implemented on the report-receiver side to handle incoming Accept(CaseProposal) activities.

The report receiver must know that the Case Actor Service accepted its proposal, so that it can match the Create(VulnerabilityCase) that follows to its own request and check its sender. The dispatcher sends each Accept(CaseProposal) to this use case.
CP-06-002 MUST A RejectCaseProposalReceivedUseCase MUST be implemented on the report-receiver side to handle incoming Reject(CaseProposal) activities.

The report receiver must know when the Case Actor Service declines its proposal, so that it stops waiting for a case. The dispatcher sends each Reject(CaseProposal) to this use case.
CP-06-003 MUST AcceptCaseProposalReceivedUseCase MUST update the report receiver's local state to reflect that the case-actor service has accepted the proposal (e.g., record the case-actor URI and await the subsequent Create(VulnerabilityCase)).

The report receiver holds no case until the CASE_MANAGER's Create(VulnerabilityCase) arrives (PCR-01-003). The record of the acceptance lets the receiver match that Create to its own request and check that it comes from the actor that accepted.
CP-06-004 MUST RejectCaseProposalReceivedUseCase MUST update the report receiver's local state to reflect the rejection (e.g., mark the pending case as rejected and surface the rejection reason if present).

Without a record of the rejection, the report receiver keeps the proposal pending and waits for a case that will not come. The reason, when the service gives one, tells the receiver's operator why, so they can decide whether to propose again (ASK-05-005).

Testing

ID Priority Requirement Related
CP-07-001 MUST Unit tests MUST cover pattern matching for all three CaseProposal extractor patterns (CREATE_CASE_PROPOSAL, ACCEPT_CASE_PROPOSAL, REJECT_CASE_PROPOSAL).

These three patterns decide whether a proposal and its answers reach their use cases at all. A missing or wrong pattern sends the activity to the wrong use case or to the handling for unknown activities, and the proposal flow stops, so each pattern needs its own test.
CP-07-002 MUST Unit tests MUST cover CreateCaseProposalReceivedUseCase, AcceptCaseProposalReceivedUseCase, and RejectCaseProposalReceivedUseCase execute() paths.

These use cases make the decisions and state changes of the proposal flow. Tests of each execute() path check that a received proposal, acceptance or rejection has its required effect, which pattern tests alone cannot show.
CP-07-003 MUST Integration tests MUST cover the full Create(CaseProposal) → Accept(CaseProposal) + Create(VulnerabilityCase) round-trip between a report receiver and a case-actor service.

Each side of the flow can pass its own unit tests while the two sides disagree on what is sent, for example on the actor, context or inReplyTo that CP-05-003 requires. Only a test that runs both sides together shows that a proposal ends in a case the report receiver accepts.

Case-Actor Service URL Configuration

ID Priority Requirement Related
CP-08-001 MUST Every actor that may propose a case for a report it receives (CP-04-001) MUST supply a case_actor_service_url value in its ActorConfig.

The Case Actor Service can run in a different container from the sender, with its own URL (DEMOMA-01-001). A sender cannot derive that URL from its own base URL: in a deployment with more than one container, that sends the proposal to the wrong endpoint. An actor URL is an opaque identifier, so nothing in it says where the service runs. This codebase has no directory service from which a sender can learn which Case Actor Service to use, so explicit configuration is the only correct source.
Uses definition from: CP-04-001
CP-08-004 MUST The case_actor_service_url field in ActorConfig MUST be a valid HttpUrl.

A non-URL value cannot be used to construct a valid inbox endpoint address, so validation at configuration load time is required to surface errors early.
Extends: CP-08-001
CP-08-005 MUST Absence of case_actor_service_url in ActorConfig MUST produce a runtime FAILURE at each BT node that needs the CaseActor identity, with a clear error message identifying the missing configuration, not a silently mis-routed proposal.

Silent mis-routing sends the proposal to the wrong endpoint without any observable error signal, making the failure hard to diagnose.
Extends: CP-08-001
CP-08-002 MUST case_actor_identity() MUST read case_actor_service_url from ActorConfig (via get_config().actor.case_actor_service_url) to derive the CaseActor service URL.

One function computes the Case Actor identity from the configured Case Actor Service URL. Every BT node that addresses the Case Actor then uses the same value, and no BT node builds it from the container's own address (CP-08-006).
Uses definition from: CP-08-001
CP-08-006 MUST NOT A BT node MUST NOT use server_base_url, from the blackboard or from the server configuration, to construct the CaseActor identity.

Using server_base_url hard-wires a co-location assumption; in a multi-container topology the CaseActor has its own container and URL.
Extends: CP-08-002
CP-08-003 MUST In all multi-container demo scenarios, every actor that may propose a case for a report it receives (CP-04-001) MUST have VULTRON_ACTOR__CASE_ACTOR_SERVICE_URL set in its Docker Compose environment block (or equivalent config mechanism).

The demo containers have no directory service to find the Case Actor Service. A variable in each container's environment gives every actor that proposes cases the service URL when the container starts. It uses the same mechanism as VULTRON_SERVER__BASE_URL, so no new discovery mechanism is needed.
Refines: CP-08-001
Uses definition from: CP-04-001
CP-08-008 MUST The VULTRON_ACTOR__CASE_ACTOR_SERVICE_URL value MUST be the full base URL of the dedicated CaseActor container (e.g., http://case-actor:7999/api/v2).

A partial URL or path-only value cannot be used to construct a valid inbox endpoint; the full base URL is required to route proposals correctly.
Extends: CP-08-003
CP-08-009 MUST NOT Demo scripts MUST NOT rely on server_base_url derivation for the CaseActor identity.

server_base_url is the running container's own base URL and does not identify a separate CaseActor container; relying on it silently routes proposals to the wrong endpoint.
Extends: CP-08-003

CASE_MANAGER-Authoritative Initialization on Accept(CaseProposal)

Requirements for the CASE_MANAGER to perform all case initialization natively when accepting a CaseProposal, per ADR-0041. These replace the receiver-side case-creation and prologue back-fill that ADR-0015 introduced.

ID Priority Requirement Related
CP-09-006 MUST The report receiver and reporter participant records MUST be created in the CASE_MANAGER's DataLayer before the CASE_MANAGER emits Create(VulnerabilityCase) to the receiver.

The receiver's replica is seeded from participant objects embedded in Create(VulnerabilityCase); participants absent at emission time leave the replica without the records required for role guards and embargo consent.
Extends: CP-09-002
CP-09-005 MUST NOT The report receiver MUST NOT create a VulnerabilityCase object in its own DataLayer before it receives Create(VulnerabilityCase) from the CASE_MANAGER.

A VulnerabilityCase that the report receiver creates for itself before the CASE_MANAGER answers is a second case object with no authority. The two copies then need extra work to reconcile them, such as a node that writes the missing ledger entries afterwards. The CASE_MANAGER creates the one authoritative case (ADR-0041), so the receiver waits for it.
CP-09-012 MUST The report receiver's receive_report_case_tree MUST store the inbound report and write a pending VultronReportCaseLink, then send Create(CaseProposal) and wait.

The stored report and the pending link are what the receiver has while it waits for the CASE_MANAGER's case. The link records whom the proposal went to (CP-06-006), so the answer and the case can be matched to the request.
Implements: CP-09-005

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

VINCE Case Translation

ID Priority Requirement Related
CRD-03-001 MUST The VINCE CaseReader adapter MUST translate each VINCE field by its VINCE crosswalk row.

The crosswalk is where a person decided each mapping. Code that departs from it makes an analysis no one agreed to.
CRD-03-002 MUST The VINCE CaseReader adapter MUST give each translated case a case reference whose link relation is issue-tracking and whose link is the VINCE case's URL.

The outside tracker's own case id rides on the case as a reference, the same rule any connector-built case follows.
CRD-03-003 MUST NOT The VINCE CaseReader adapter MUST NOT refuse a case for a VINCE value its crosswalk does not know.

A new VINCE status value is a gap in the mapping, and the analyst still needs the rest of the case. The value comes back as an untranslated fact (CRD-03-004).
CRD-03-004 MUST The VINCE CaseReader adapter MUST return a VINCE value its crosswalk does not know as an untranslated fact with the unknown-value reason.

The analyst sees which value the mapping lacks, beside the rest of the translated case.
CRD-03-005 MUST Every inference the VINCE CaseReader adapter returns MUST name the crosswalk row identifier that produced it.

The dashboard links each inferred state to the row a person agreed to.

Case Shadow Tool

Rules for the case shadow tool: a standalone, read-only tool that reads one case from an outside system on request, translates it, and shows Vultron's analysis of it, and how that tool is packaged. The first outside system is VINCE; its data rules are in vince-shadow-data.yaml.

File ID: SHD

Read-Only Advisor

ID Priority Requirement Related
SHD-01-001 MUST NOT The case shadow tool MUST NOT contain a code path that delivers an activity to an inbox.

This version of the case shadow tool advises the people working a case and does not act in it. With no delivery path, nothing can reach a participant, whatever its settings.
SHD-01-002 MUST NOT The case shadow tool MUST NOT write to an outside system.

A case shadow tool beside an outside system that holds the case of record must leave that record exactly as its users left it.
SHD-01-003 MUST NOT The case shadow tool MUST NOT leave a case it read, or its translation, on the host after its process exits.

A copy left on the host is a second store of embargoed data that nobody planned to protect. Holding a case in memory while the process runs is allowed, so the tool can follow a live case as its ledger grows, and so is a transient working file that is gone when the process exits. A later need for the case is met by reading it again. The tool's Compose service has no persistent volume to write to (SHD-02-001).
SHD-01-004 MUST The case shadow tool MUST show every outside-system fact its case reader could not translate, beside the analysis of the case.

An analysis that silently leaves out part of the case looks complete when it is not. Shown facts tell the analyst what the scores do not cover.
Depends on: CRD-01-005

Packaging

ID Priority Requirement Related
SHD-02-001 MUST NOT The case shadow tool's Compose service MUST NOT mount a persistent volume.

With nowhere persistent to write, a bug cannot leave a copy of a case behind when the container stops.
SHD-02-002 MUST The case shadow tool's Compose service MUST publish its port on the loopback interface only.

The page shows embargoed case data. Publishing it on loopback keeps it off the network the host sits on.
SHD-02-003 MUST The case shadow tool MUST read the outside system's credential only from the environment it runs in.

The credential is a secret, so it is kept outside the code, the repository and every configuration file. An image or a compose file is shared and often committed, and a credential that only the running environment holds has no path into either.
SHD-02-004 MUST NOT Code outside the case shadow tool MUST NOT import Streamlit.

Streamlit is sanctioned for the case shadow tool only. Keeping it there keeps the protocol packages free of a user-interface dependency.

Move Advice

ID Priority Requirement Related
SHD-03-001 MUST The case shadow tool's move advice MUST give each open move one outcome shift for each vendor of the case, notified or not, each read from that vendor's own projection of the case onto each desideratum's smallest model, so that the advice never joins several vendors' sequences into one (CEH-05-006).

A vendor's scope is the unit of move advice. Each vendor's values come from its own projection, so the advice reads several vendors as the event-history layer exposes them. A vendor not yet notified is a scope too: the spike of #6450 shows that a score over the notified vendors alone marks a notice as a loss.
See also: CEH-05-006 — The same boundary at the event-history layer; the advice keeps it, but it is not a case of that rule.
SHD-03-002 MUST NOT The case shadow tool's move advice MUST NOT put the open moves in order by one score that combines the vendors' scores.

In the spike of #6450, each of five scalar aggregates (median, mean, maximin, mean then spread, Nash product) fails pathology cases that the bands pass: a scalar names no vendor's harm, and four of the five rank an embargo move above notifying a vendor.
SHD-03-003 MUST Each shaded band of the case shadow tool's move advice MUST show a colour legend strip drawn from that band's own colour map, with one cell per layer in the shade that layer's rows take, labelled from better (layer 1) to dominated (deeper layers).

Layers in different bands are not comparable, so each band has its own legend. A legend in its rows' exact shades shows the analyst which end of the gradient is better without asking them to remember it.
SHD-03-004 MUST The case shadow tool's move advice help text MUST tell the analyst, without naming a colour, to prefer the harm-free band and that, inside a band, the moves at the legend's better end are dominated by no other move.

The help text reads the bands and the legend as one piece of advice, in terms of dominance rather than a colour the analyst must match by eye.

Live Vultron Case Reader

ID Priority Requirement Related
SHD-04-001 MUST NOT The live Vultron case reader MUST NOT send a node any request other than a GET of a case's ledger list endpoint or its ledger event-stream endpoint.

The reader reads a running node's case; any other request could change the case or act in it, which the case shadow tool never does. The ledger read endpoints are the node's demo-only, prototype-mode list and event-stream endpoints; an access-controlled read surface for a production node is a separate decision.
Refines: SHD-01-001
SHD-04-002 MUST The live Vultron case reader MUST raise a domain error naming the node and the case when it cannot read the case from the node.

The read fails when the node cannot be reached, does not serve the case ledger read endpoints, which exist only on a node in prototype mode, or holds no such case. An error that names the node and the case tells the analyst where to look, instead of a dashboard that shows an empty case.
SHD-04-003 MUST Each case reading the live Vultron case reader returns MUST hold every ledger entry the node has sent for the case, in log-index order.

An analysis built on part of a ledger looks complete when it is not. A followed case is read again whole as each entry arrives, so every reading the dashboard shows is a whole ledger, exactly as a file reading is.
SHD-04-004 MUST The live Vultron case reader MUST refuse a case reading whole when any entry the node sent for it is not a valid ledger entry.

Dropping the bad entry would give a partial ledger that looks whole. The file reader refuses a bad row the same way.
Refines: SHD-04-003
SHD-04-005 MUST The case shadow tool MUST keep showing a followed case's last accepted reading, marked, after a later reading is refused or the stream ends.

A refused entry or a stopped node does not make the case's earlier standing wrong. Keeping it on the page, marked, tells the analyst what they are looking at without blanking the dashboard.
Depends on: SHD-04-004

Action Rules

ID Priority Requirement Related
SHD-05-001 MUST An action rule MUST read one vendor's position. The position is the vendor's RM, CS and PEC states and the case's EM state.

Move advice scores each move for one vendor's scope, read from that vendor's own projection (SHD-03-001). A rule that reads the same position can be checked against that advice. A rule over CS alone cannot say that a move suits an RM or EM state. The PEC states are the vendor's consent to the embargo in force and to an open proposal.
SHD-05-002 MUST An action rule for a role other than the vendor MUST match once for each vendor whose position matches it, and name that vendor.

A rule is advice and fires nothing, so it does not need a threshold over the vendors. Naming the vendor tells the analyst which vendor the advice is about, and the trigger that acts on it still aggregates over the participants.
SHD-05-003 MUST The case shadow tool MUST treat a rule as undecided where it constrains a part of the position that the case reading does not hold.

A reading that records no state for a part, such as no embargo consent, says nothing about it. A rule shown as matched or unmatched there would read an unknown as false, which CRD-02-005 rules out for the facts a case reader declares unobservable.
SHD-05-004 MUST Each action rule MUST name its roles, one action and its reason, and the desiderata the action serves where its reason is one. Its roles are a set of CVD roles, or any role. Each desideratum comes from the move-advice desiderata list.

A rule always has a reason, but not every reason is a desideratum: situation awareness, detection, defense and housekeeping are reasons that order no events (user decision on #6676, D10 and D11). A reason that names desiderata lets the comparison check the rule against the advice. A rule whose reason names none is still a suggestion; the comparison shows it with its reason and no number (SHD-05-028). Any role constrains no role, as the EM trigger roles table's empty entry does.
SHD-05-005 MUST An action rule whose action is a move MUST name the move as move advice names it, by its state machine and its trigger.

The comparison joins a rule and the advice for the same move on one name. A second name for a move would leave the two unjoined, and the rule would read as unscored.
SHD-05-006 MUST The source pairs of the carried-over rules MUST equal the pairs of CS_ACTION_RULES, less the pair that initiates the Vulnerabilities Equities Process.

The CS action rules are held equal to the legacy test oracle over the 32 valid compound states (CSB-17-001). An authored table that drops or adds a source pair would give advice that the oracle no longer checks. The Vulnerabilities Equities Process is a US government policy, not a move of the protocol, so its rule does not carry over.
SHD-05-007 MUST Each generated action rule MUST take its verdict from move advice as the move's band for one vendor. The band is read at a position with the desiderata still open there. It is harm-free when the vendor's deciding part is positive, and unhelpful otherwise.

The generated rules are the evidence that an authored rule is checked against. A second scorer could drift from the advice. The deciding part is the vendor's end part, or its embargo part when the end part is zero, as the bands use, and the band combines no vendors' scores (SHD-03-002). A desideratum already met or broken changes by nothing, so one move can get two bands at one position from two histories (#6676, D6).
SHD-05-008 MUST This codebase MUST provide one command that rebuilds the generated action rules and their docs page.

A person who edits the rules by hand could hide a blind spot of the chance model. One command makes the generated rules follow the advice.
SHD-05-009 MUST A check MUST fail when the committed generated action rules or their docs page differ from what the command builds from the current move advice.

A change to move advice that leaves the generated rules unchanged would compare the authored rules with advice that no longer holds.
Depends on: SHD-05-008
SHD-05-010 MUST The comparison MUST give one result for each authored rule that matches a position. The result is agreement, rule disagreement, misplaced rule or unscored rule.

An agreement is an authored claim on a move that is harm-free for the vendor, and a rule disagreement one on a move that is unhelpful for it. A misplaced rule names a move the state machines do not allow there, or one that the rule's role may not make. An unscored rule names an action with no band. Each result tells the analyst something different, so none may fold into another.
SHD-05-011 MUST The comparison MUST join an authored rule to move advice on the move name and on the participant the move is for.

A move name carries no participant. For an RM or CS move the participant is the matched vendor whose state the move changes; for an EM move it is the participant in the rule's role that move advice lists as able to make it. Without the participant, a rule about one vendor could join the advice for another.
SHD-05-012 MUST Each agreement and each rule disagreement MUST carry the deciding part of the vendor's shift and the change in each desideratum the rule names.

The verdict is a band from all of the vendor's desiderata. A rule that names an end desideratum can agree with a move whose band comes from its embargo part only, and these two values let the analyst see that.
SHD-05-013 MUST NOT The comparison MUST NOT change an authored action rule or a generated action rule.

Neither the rules nor the chance model is ground truth. A rule disagreement marks a wrong rule or a blind spot of the model, and only a person can tell which, so a comparison that resolved it would hide one of the two.
SHD-05-014 MUST Each rule disagreement of an authored rule that cites a chance-model blind spot MUST carry the issue that the rule cites.

A person who judges a disagreement a blind spot of the model keeps it shown, with the issue that tracks the blind spot, so the analyst sees that it is known and why.
SHD-05-015 MUST The generated action rules MUST group, for each move, the valid positions of one vendor where the move always gets the same band. Always means for every set of desiderata a history can leave open there. Each group is written as one or more patterns in the pattern language of the authored rules.

A generated rule states move advice in the language a person writes rules in, so the two can be read side by side and compared position by position. A pattern that covered a position of the other band would state advice that move advice does not give. A position where the band depends on the history is not in any group; SHD-05-029 states it as a conditional verdict.
Depends on: SHD-05-007
SHD-05-016 MUST Each generated action rule MUST carry the role that move advice gives its move. For an RM or CS move, that role is the vendor. For an EM move, it is the role that EM_TRIGGER_ROLES gives the trigger, or any role when that table names none.

An RM or CS move names the vendor whose state it moves, and an EM move the participant who may make it. A generated rule with another role would not join the authored rules for the same participant.
SHD-05-017 MUST NOT The command of SHD-05-008 MUST NOT generate a rule for a move that move advice does not score.

A move with no band has no verdict to group, such as a PEC move while move advice has no PEC moves (#6677). An authored rule for such a move is an unscored rule, never an agreement.
Depends on: SHD-05-008
SHD-05-018 MUST An action rule whose action is not a move at every position it matches MUST name the action by its member of Actions.

A CVD action such as monitoring for attacks has no move and no band, and a publication is a move only where its event has not yet happened (SHD-05-024), so the legacy action name is the one name that holds at every position.
SHD-05-019 MUST This codebase MUST hold one mapping that gives the move name for each member of Actions that changes state.

The carried-over CS rules name their actions by Actions member. One mapping turns each state-changing member into the move name that move advice uses, so a second copy cannot drift from it.
SHD-05-020 MUST An action rule whose PEC part reads an open proposal MUST match once for each open proposal that its pattern matches, and name that proposal.

A vendor's consent can differ between two open proposals. Naming the proposal tells the analyst which proposal the advice is about.
SHD-05-021 MUST The comparison MUST give an unclaimed-move result for each harm-free verdict at a position that no authored rule matching there names.

A harm-free move that no rule names is advice the authored table misses. An unhelpful move that no rule names needs no result, because no rule claims it and move advice does not recommend it.
SHD-05-022 MUST Each carried-over authored rule MUST record the CS_ACTION_RULES pattern and action that it came from.

A person narrows a carried-over rule and sets its roles and desiderata, so its pattern and action can differ from its source. The recorded source keeps the rule tied to the legacy oracle that checks the source pair.
SHD-05-023 MUST NOT A carried-over authored rule MUST NOT match a position whose CS state its source pattern does not match.

A person may narrow a carried-over rule with RM, EM or PEC parts, or with a narrower CS pattern, but a rule that widened its source would give advice at CS states that the legacy oracle never checked.
Depends on: SHD-05-022
SHD-05-024 MUST The comparison MUST treat an action at a position where the CS event it causes has already happened as an action that changes no state.

Publication is any publication, such as an advisory, exploit details, a detection or a mitigation, and it is always a valid action. Only the first publication causes P, and the same holds for X and A, so a later publication is valid and changes no state. Calling it a misplaced rule would read a valid action as an authoring error.
SHD-05-025 MUST NOT The case shadow tool MUST NOT drop a move from the moves it shows because of an authored action rule.

An action rule suggests an action and never forbids one. A move that no rule names stays open, and a move that a rule shows to be costly, such as publishing before the vendor is aware, is shown with its cost.
SHD-05-026 MUST A carried-over authored rule whose action is an EM move MUST match only EM states from which that move exists.

The carried-over rules predate the EM machine. Negotiating an embargo at ..dpxa is a proposal at EM NONE, and at EM PROPOSED an acceptance by the case owner or a participant's answer to the proposal; a termination exists only while an embargo is in force.
Depends on: SHD-05-022
SHD-05-027 MUST A carried-over close-case rule MUST name rm.close and match only a participant whose RM state is not CLOSED.

Closing the case is the RM move each participant makes for itself, so it is scored as an RM move and disappears once that participant has closed. A condition such as "unless monitoring for attacks" stays reason text.
SHD-05-028 MUST The comparison MUST give an unscored-rule result, with the rule's reason, for a matching rule that names no desideratum.

A rule whose reason is not a desideratum, such as monitoring for attacks or closing a finished case, claims no outcome a band could check. Shown as a rule disagreement, it would read as a wrong rule; shown with its reason and no number, it reads as the suggestion it is (user decision on #6676, D10, D16).
SHD-05-029 MUST The generated action rules MUST state each band of a conditional verdict with the desiderata whose state gives it. A conditional verdict is a move at one valid position of one vendor that gets different bands for different sets of open desiderata.

A case-free table cannot pick one history, and a blank line hides the advice. A report accepted and then deferred and one deferred straight away stand at the same position, but accepting the report helps only the second, whose acceptance desiderata are still open (user decision on #6676, D6).
Depends on: SHD-05-007
SHD-05-030 MUST NOT The comparison MUST NOT join a publication to the public's awareness at a position where a public exploit forces that awareness next.

A public exploit means the public knows the vul exists; it does not mean a participant published information defenders can use (user decision on #6676, D10). Joining a deliberate publication to that forced event would score the exploit as the publication's work.

Action Rules on the Page

ID Priority Requirement Related
SHD-06-001 MUST The case shadow tool MUST show the authored rules that match each vendor's position beside the move bands. The position is the one at the point the analyst looks at.

The analyst reads a person's claim beside the model's evidence. A rule that is not on the page cannot be checked against the bands it sits next to.
SHD-06-002 MUST The case shadow tool MUST compare each rule it shows with the move's band for the matched vendor, read from the case's own outcome shifts.

A live case can have vendors that a move helps and vendors that it harms. Comparing with the matched vendor's own band shows a trade-off move as an agreement for one vendor and a rule disagreement for another.
Depends on: SHD-05-007
SHD-06-003 MUST The case shadow tool MUST flag each rule disagreement and each misplaced rule it shows.

A disagreement marks a wrong rule or a blind spot of the model, and a misplaced rule marks an authoring error. Either one, left unflagged, reads as advice that agrees with the bands.
SHD-06-004 MUST The measuring-CVD docs MUST hold a generated page that lists the generated action rules and the comparison's result at every valid position of one vendor.

The page states move advice as rules that a person can review one by one, and shows every disagreement in one place, not only the ones a live case reaches. The command of SHD-05-008 builds it.
SHD-06-005 MUST The command of SHD-05-008 MUST generate the rules table of docs/topics/other_uses/action_rules.md from the carried-over authored rules.

The page's table and CS_ACTION_RULES have drifted: the table splits or merges rules, two of its patterns are typos, and some rules have no row. A table built from the authored rules shows each rule's pattern, roles, action and desiderata as the authored table holds them, so the two cannot disagree.
Depends on: SHD-05-008
SHD-06-006 MUST The case shadow tool MUST show each undecided rule as undecided and each unscored rule with no number.

An undecided rule constrains a part the reading does not hold, so showing it as matched or dropping it would read an unknown as known (SHD-05-003). An unscored rule has no band, so a number beside it would read as an agreement.
SHD-06-007 MUST The generated page MUST show an authored rule with a PEC part as undecided.

The chance model holds no PEC state, so the page's positions hold none, and a rule that constrains PEC is neither matched nor unmatched there (SHD-05-003).
Depends on: SHD-06-004

Code Style Specifications

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

File ID: CS

Code Formatting

ID Priority Requirement Related
CS-01-001 MUST Code MUST follow PEP 8 style guidelines

PEP 8 is the style most Python contributors already know. One shared style lets a reader follow any module without first learning a local one. The E and W pycodestyle rules that ruff check selects in pyproject.toml check much of it, and ruff format sets the layout.
CS-01-004 SHOULD Functions and methods SHOULD have docstrings following PEP 257 conventions

A docstring tells a reader what a function does and what it expects without reading its body. The code reference pages under docs/reference/code/ are built from docstrings by mkdocstrings, so a missing docstring is also a gap in the published reference. No lint rule checks this; review does.
CS-01-005 SHOULD Docstrings SHOULD follow Google style for structured sections

mkdocstrings parses Google-style Args:, Returns: and Raises: sections into structured entries on the code reference pages. One style for every module gives each reader the same layout and gives the parser one format to read.

Import Organization

ID Priority Requirement Related
CS-02-001 SHOULD Imports SHOULD be organized in three groups: standard library, third-party libraries, local application

The three groups show at a glance which dependencies come from outside the project. A fixed order also means two contributors write the same import block, so a diff shows only the imports that really changed. The I001 rule in ruff check reports an import block that is not grouped and sorted.
CS-02-002 SHOULD Import statements SHOULD be placed at the top of the file after module comments or docstrings

Imports at the top show all of a module's dependencies in one place. An import lower in a module runs later than a reader expects and can hide an import cycle (CS-05-005). The E402 rule in ruff check reports a module-level import that is not at the top.
CS-02-003 SHOULD Multi-line import statements SHOULD use parentheses for readability

Parentheses let ruff format put one name on each line. A diff that adds or removes a name then changes one line. A backslash continuation breaks when a space follows the backslash.

Import Practices

ID Priority Requirement Related
CS-03-001 MUST NOT Code in this project MUST NOT use a wildcard import, such as from module import *, outside vultron/wire/as2/vocab/examples/vocab_examples.py.

A wildcard import hides where a name comes from, so a reader and a type checker cannot tell which names a module defines. A name that the source module adds later can also replace a local name without warning. In ruff check, F403 reports a wildcard import, and F405 reports a name that can come from one. vocab_examples.py gathers its sibling example modules for the docs pages, so it is the one exception. A test makes sure its wildcard imports never replace a name.
CS-03-005 MUST Each wildcard import in vultron/wire/as2/vocab/examples/vocab_examples.py MUST carry a # noqa: F403 marker that cites CS-03-001.

The marker tells ruff check that the wildcard import is intended. The citation tells a reader which rule allows it, so the exception does not look like a mistake.
Refines: CS-03-001
CS-03-002 MUST Unused imports MUST be removed

An unused import adds a dependency that does nothing. It makes a module load code it does not use, and it can create an import cycle with no reason. The F401 rule in ruff check reports it. __init__.py files are exempt in pyproject.toml, because there an import re-exports a name.
CS-03-003 MUST When importing more than 10 items from a module, import the module itself instead

Reduces line noise and makes module boundaries clearer
CS-03-004 SHOULD In test modules, avoid multiple imports from the module under test; consider importing the module and using attribute access for clarity.

A test that imports the module under test and uses module.name shows at each use which module a name comes from. The import list then stays short as the test file grows.

Import Style Preferences

ID Priority Requirement Related
CS-04-001 MAY Relative imports MAY be used for local application imports when appropriate

Inside one package, a relative import is short and keeps working when the parent package moves. The permission records that neither form is a defect, so a review does not ask for a rewrite of one to the other.
CS-04-002 MAY Module imports MAY use aliases for clarity or to avoid naming conflicts

Two modules can export the same name, for example a wire class and a core class. An alias lets one module use both without a clash, and it can give a long module path a short, clear name.

Circular Import Prevention

ID Priority Requirement Related
CS-05-002 SHOULD A circular dependency SHOULD be resolved by reorganization first (a neutral module per CS-05-003, or moving the shared symbol to the side of the cycle that owns it). Deferring the import into a function body is a last resort that hides the cycle rather than removing it, and every such deferral is tracked toward structural removal (CS-05-005).

A function-local import hides a cycle but does not remove it. The cycle stays in the module graph, and the next import that reaches it fails at load time or needs one more deferral. Reorganization removes the cause, so the cycle cannot come back through a different import. Most function-local imports break no cycle at all, and module level is the right place for them.
See also: CS-05-003 — context for the reader
CS-05-005 MUST In production code under vultron/, a function-local import MUST exist only to break an import cycle that reorganization has not yet removed. An import with no cycle to break goes at module level.

A function-local import hides a dependency from the top of the module. When each one breaks a known cycle, the set of such imports is the list of cycles still to remove.
Refines: CS-05-002
CS-05-007 MUST Each function-local import in vultron/ MUST carry a # noqa: PLC0415 marker whose trailing comment names the issue that tracks its structural removal (the IMPLTS-07-020 baseline form). A TYPE_CHECKING-guarded import is not a function-local import and needs no marker.

The marker makes each deferred import visible in review, and its comment names the issue that removes the cycle. A new function-local import without a marker fails ruff check under PLC0415. RUF100 (unused-noqa) stays selected, so a marker left behind after its import moves to module level also fails. The markers in vultron/ therefore list every function-local import that remains.
Extends: CS-05-005
Refines: IMPLTS-07-020
CS-05-006 MAY Test modules under test/ MAY import inside test functions and fixtures. This idiom is exempted from PLC0415 through a per-file-ignores entry for test/** rather than through per-site markers.

A test-local import scopes a dependency to the one test that needs it and keeps a module-under-test out of collection-time import order (isolated_core_registries, monkeypatch of module attributes). It is an isolation idiom, not a cycle break, so CS-05-002 does not govern it and CS-05-005's marker discipline would add noise without a backlog to drain.
CS-05-004 MUST Before adding imports between modules, trace the import chain to prevent cycles

An import cycle fails at load time, often in a module other than the one a change edited. A function-local import that hides a cycle is a last resort, and each one needs a tracked marker (CS-05-002, CS-05-005). So a cycle found after the fact costs a reorganization of modules. Tracing the chain first finds the cycle before the import exists, when a different placement costs nothing.

as_ Field Prefix Policy

ID Priority Requirement Related
CS-07-001 MUST NOT Pydantic field names MUST NOT use the as_ prefix anywhere in the codebase. Class names (e.g., as_Activity, as_Object) keep the as_ prefix as an ActivityStreams provenance marker.

Field names become wire keys through the to_camel alias generator. A field named as_object would serialize as asObject, which is not an ActivityStreams key. On a class name the prefix marks ActivityStreams vocabulary. On a field it adds no information and gives the wrong key.
CS-07-002 MUST For fields whose plain name collides with a Python builtin or reserved word (e.g., object, type, id, context), use a trailing underscore: object_, type_, id_, context_

Idiomatic Python (PEP 8); keeps models readable and decoupled from AS2 naming conventions.

Optional Field Non-Emptiness

ID Priority Requirement Related
CS-08-001 MUST NOT Optional string fields MUST NOT contain empty strings when present; the invariant is "if present, then non-empty"

Distinguishes "not provided" from "provided but blank", avoiding ambiguous database states. It covers the wire AS2 reference properties (to, context, inReplyTo, ...) too: a blank IRI names nothing. Lenient inbound parsing (ARCH-21-002) means accepting every shape AS2 allows, and a blank is none of them. ARCH-12-004 no longer exempts Any &#124; None wire types; it constrains only validators that read case state or stored data (#3894).
CS-08-002 SHOULD Non-empty string validation SHOULD be consolidated into a shared type alias rather than duplicated per-field validators

Reduces boilerplate and makes the invariant visible in the type signature rather than buried in a per-field validator.
Implements: CS-08-001

Code Reuse

ID Priority Requirement Related
CS-09-002 SHOULD Pydantic request and response models for API endpoints SHOULD be reused or inherited rather than duplicated

Duplicated models diverge silently over time; a hierarchy makes the relationship explicit and reduces boilerplate

Port and Adapter Data Exchange

ID Priority Requirement Related
CS-10-003 MUST A port boundary type MUST be a named Pydantic model class, not a plain dict or a bare BaseModel subclass with no semantic meaning. Examples are VulnerabilityCase and CaseParticipant.

A bare BaseModel at a port says no more about its content than a dict: any model passes the type check. A named domain type lets mypy and pyright reject a wrong object at the call site, and it tells the reader what crosses the port. CS-10-001 states the general rule; this is its Python form.
Implements: CS-10-001 — Python/Pydantic-specific application of the typed-port-boundary pattern
CS-10-005 MUST A port Protocol signature in this codebase MUST declare its parameters and return values as the named domain model classes of CS-10-003.

mypy and pyright check a call against the Protocol signature. When the signature names the domain class, the checkers reject a dict or an unrelated model at the call site.
Implements: CS-10-004 — Python form of the typed port signature
Extends: CS-10-003
CS-10-002 SHOULD A wire-level ActivityStreams payload class SHOULD carry the Activity suffix.

Distinguishes wire representation from domain intent, prevents accidental coupling between layers, and makes the translation point explicit. See notes/wire-core-boundary.md for the rationale.
CS-10-006 SHOULD A domain event class SHOULD carry the Event suffix.

The suffix tells a reader that the class is the domain meaning of a message, not its wire form. The Activity suffix (CS-10-002) marks the wire form, so the two never look alike.
Extends: CS-10-002

Type Annotations

ID Priority Requirement Related
CS-11-001 MUST NOT Code MUST NOT use Any in type hints when the type can be determined

Any defeats static type checking, obscures API contracts, and hides bugs at the boundary between typed and untyped code

Domain Model Naming

ID Priority Requirement Related
CS-12-001 SHOULD Core domain model class names SHOULD reflect the domain concept they represent, not a parallel to a wire-format class name

Generic wire-mirroring names obscure what an object actually represents in the CVD domain. Domain-centric names make the code self-documenting and reduce reliance on comments to explain intent.
CS-12-002 SHOULD A use-case class that handles an inbound received message SHOULD carry the ReceivedUseCase suffix, as in ValidateReportReceivedUseCase.

Distinguishes messages received from external parties from actions the local actor has decided to take. This distinction is fundamental to the Vultron protocol model (see notes/activitystreams-semantics.md) and prevents accidentally treating incoming messages as local commands.
CS-12-003 SHOULD A use-case class for a local actor-initiated trigger SHOULD carry the Svc prefix and the UseCase suffix, as in SvcEngageCaseUseCase.

A reader can then tell at a glance an action the local actor decided to take from a message that another party sent (CS-12-002). The prefix marks the class only: a trigger-side module function takes a _trigger suffix instead.
Extends: CS-12-002

Datetime and Timezone Conventions

ID Priority Requirement Related
CS-13-002 MUST Application code MUST read the current time only at an act's entry point, through the act clock port (ClockPort in vultron.core.ports.clock), once per act: for a trigger or a sweep after the act takes the tree lock, and for a received message once on its arrival at the inbox, before it queues for the tree lock (CS-13-010). Two other reads are permitted: an adapter's own bookkeeping times, read through BookkeepingClockPort, and stopwatch reads at named sites.

An act that reads the clock twice can decide against one instant and record against another, and a read that commits nothing still moves a recorded run's clock (ADR-0176). One read per act, through one injected port, gives the act's decisions and stamps one instant. The system clock behind the port reads through now_utc(), so each time keeps its CS-13-001 form.
CS-13-010 MUST Every act that processes a received message, its replays, retries and restart re-runs included, MUST take as its instant the message's arrival stamp, the received_at the receiver records for the message.

The receiver's backlog is not the sender's to bear: a message that arrived before a deadline is on time however long it waited for the tree lock (ADR-0176). The stamp is the receiver's own reading, which the sender cannot set as it can set published. One stamp, carried on the held record, keeps a replay's verdict the one the message would have had on arrival.
Refines: CS-13-002
CS-13-004 MUST An embargo deadline datetime MUST be computed as the act's instant plus a duration, through the deadline_from(at, delta) / days_after(at, n) helpers in vultron.core.models._helpers, rather than by inline arithmetic or from a clock read.

An embargo deadline is a protocol commitment that every Participant compares with its own clock. The helpers measure each deadline from the act's instant, so the deadline agrees with the act that set it (ADR-0176), and they return it in UTC and refuse a naive instant, so it is timezone-aware. Inline arithmetic can start from a naive or local time and give a deadline that peers read as a different instant.
CS-13-008 MUST The now_utc() helper in vultron.core.models._helpers MUST keep the microseconds of the instant it reads.

Two acts one actor sends inside one second then carry ordered times, so a same-second tie is rare rather than routine (ADR-0167). The fixed form of CS-13-007 writes the microseconds, so keeping them costs no second string for one instant.
Refines: CS-13-007 — the clock half of the fixed-form decision

Wire Model Configuration

ID Priority Requirement Related
CS-14-001 MUST Wire-layer Pydantic models (classes in vultron/wire/as2/vocab/) MUST inherit model_config from as_Base, which sets alias_generator=to_camel, validate_by_name=True, and validate_by_alias=True

One inherited model_config gives every wire class the same mapping from Python field names to camelCase ActivityStreams keys. A class with its own settings could serialize a field under the wrong key, or refuse a valid inbound key. The two validate_by_* settings let a model accept both the wire key and the Python name.
CS-14-002 MUST Core/domain-layer Pydantic models (classes in vultron/core/models/) MUST set populate_by_name=True in their model_config

Core code builds objects with Python field names such as id_ and type_, while stored rows and serialized forms use the alias spelling. With populate_by_name=True, one model accepts both spellings, so core code does not need to know the alias to build an object.
CS-14-003 MUST Domain event subclasses MUST narrow the semantic_type field to a Literal[MessageSemantics.FOO] type with the corresponding default value

The Literal ties each event class to one MessageSemantics value. Pydantic then refuses an event built with a different value, so an event cannot claim a meaning its class does not handle. The default fills the value, so a caller does not repeat it.

No Compatibility Shims

ID Priority Requirement Related
CS-15-001 MUST When a refactor moves or replaces a module, function, variable or symbol, the author MUST delete the old symbol. A compatibility alias, re-export or shim kept only to avoid updating call sites is prohibited. A split package's __init__.py that re-exports the old module's public names (CS-18-003) is that module's public import path, not a shim.

The codebase is in prototype development; there are no external downstream consumers that require stable import paths. Leaving old symbols in place accumulates technical debt and makes the codebase harder to navigate.

Method and Variable Naming Safety

ID Priority Requirement Related
CS-16-001 MUST NOT Methods and class-level variables MUST NOT be named after Python built-in types (list, dict, set, tuple, type, object, int, str, float, bool, bytes, etc.)

Defining def list(self, ...) in a class body shadows the built-in list type for all subsequent annotations and expressions in that class scope. Any annotation like list[str] that appears after the method definition resolves to the method (a function), producing a TypeError at runtime. A # type: ignore comment suppresses mypy but does NOT prevent the runtime error. Rename the method to avoid the collision (e.g., list_objects).

Pydantic Models for Structured Data

ID Priority Requirement Related
CS-17-001 MUST CLI tools and any code that reads or writes structured files (YAML frontmatter, JSON, structured config) MUST define a Pydantic model for the file structure rather than using dict.get() with fallback defaults.

Ad-hoc metadata.get("field", "") access makes it impossible to distinguish "absent field" from "empty field", silently allows invalid data through, and scatters validation logic across callers. A Pydantic model with ValidationError on missing required fields is the single source of truth and forces callers to handle the error path explicitly.

Module Size and Organization

ID Priority Requirement Related
CS-18-001 SHOULD A Python source file SHOULD NOT exceed 500 lines when it mixes multiple distinct responsibilities.

Large, multi-responsibility files accumulate technical debt, slow review cycles, and make targeted test coverage difficult. High-churn large files are especially prone to merge conflicts. The 500-line threshold is a practical signal, not a hard language constraint — a coherent single-responsibility module MAY exceed it if all concerns are tightly related. The key signal is mixed responsibility.
CS-18-005 MUST When a module that mixes responsibilities crosses the 500-line threshold, an author MUST split it into a subpackage whose submodules are grouped by semantic concern.

A subpackage keeps each concern in its own submodule, so a change to one concern touches one small file. Review, tests and merges then deal with less unrelated code.
Extends: CS-18-001
CS-18-002 MUST Each submodule of a split subpackage MUST itself meet CS-18-001 and CS-18-005. A submodule over 500 lines that mixes responsibilities is then split again.

Splitting a god module into a package does not eliminate the problem if individual submodules re-accumulate size. A recursive constraint closes this loophole.
Refines: CS-18-001
Refines: CS-18-005
CS-18-003 MUST A subpackage created by splitting a flat module MUST re-export all previously public names from its __init__.py to preserve import compatibility with callers.

A split changes how a module is organized, not what it offers. When the package __init__.py exports every public name of the flat module, an import such as from vultron.foo.nodes import SomeNode keeps working. The split then changes no caller, and its diff holds only the moved code.
Refines: CS-15-001
CS-18-004 SHOULD Each subpackage split from a flat module, and each BT nodes/ subpackage (BTND-07-001), SHOULD have mirrored tests: one test_<submodule>.py per submodule.

A monolithic test file grows in parallel with the flat module and inherits the same blast-radius problem. Mirrored test files scope failures to the affected concern, keep each concern's tests together and runnable alone, and make it easier to add focused per-unit tests.
Extends: BTND-07-001

Protocol and Type-Guard Hygiene

ID Priority Requirement Related
CS-20-001 MUST When an author removes a member from a class that conforms to a Protocol, the author MUST remove its Protocol declaration too, and the reverse.

mypy and pyright check only one direction: that a concrete class satisfies the Protocol. They do not report a Protocol member that no concrete class has any more. A caller typed against the Protocol can then use that member, pass the type check, and fail at runtime.
CS-20-003 MUST NOT A Protocol MUST NOT keep a member declaration that no conforming concrete class still has.

A stale member lets a caller typed against the Protocol use something that no object provides. The type check passes, and the call fails at runtime.
Extends: CS-20-001
CS-20-002 MUST TypeGuard discriminator functions (e.g., is_case_model()) MUST use only fields or methods that are explicitly declared on the target Protocol as their hasattr/isinstance checks. Using a method or field that is NOT in the Protocol as a discriminator is forbidden.

A guard that tests a member outside the Protocol depends on a detail that the Protocol does not promise. When that member goes away from the concrete class, the guard returns False for valid objects and gives no error. Code that relies on the guard can then skip those objects, far from the cause. A guard that tests only Protocol members stays correct for as long as CS-20-001 keeps the Protocol current.

Test Fixtures Mirroring Production Enums

ID Priority Requirement Related
CS-19-001 MUST A test fixture or constant that enumerates the same value set as a production enum (e.g., a list of expected semantic-type strings mirroring MessageSemantics) MUST derive its values from the enum at import/collection time rather than duplicating them as separately-maintained literals.

A copied list of enum values does not change when the enum changes. After a rename, the test then checks for values that the enum does not have, and it can pass while it checks nothing. A list built from the enum follows each rename, and an exclusion that names a removed member fails at collection time, where the cause is clear.

Collection-Typed Pydantic Field Defaults

ID Priority Requirement Related
CS-21-001 MUST NOT Pydantic model fields whose type is a collection (dict, set, list, or any generic alias thereof) MUST NOT use None as their default value when the intent is "empty collection if not provided". Use Field(default_factory=list), Field(default_factory=dict), or Field(default_factory=set) matching the field's collection type. None is only acceptable as a field default when it is an intentional sentinel meaning "absent" (as distinct from "empty"), and that distinction must be observable in the model's behaviour or serialisation. Plain function and method parameters are out of scope for this rule: param: set[str] &#124; None = None with an x or set() guard in the body is the correct idiom for optional collection parameters, as it avoids the Python mutable-default-argument hazard (= set() shares a single object across all calls that omit the argument).

A None default for a collection gives two values for "nothing here". Every reader must then guard against None before it can iterate, and a missed guard fails at runtime. An empty default gives one value. Function parameters differ: a = set() default is one object shared by every call, so there the None sentinel with an x or set() guard is the safe form.

Extract Before Reuse

ID Priority Requirement Related
CS-22-001 SHOULD Shared logic SHOULD be extracted to a dedicated helper module before it is used in a second location. Three similar lines of code is a signal to extract; copy-pasting a function body is not acceptable. DRY is a project standard.

Copied code copies its defects too. A later fix then has to find and change each copy, and a missed copy keeps the defect. Extraction after many copies exist costs more, because the copies have usually changed in small ways that must be reconciled first. Extraction at the second use keeps one implementation from the start.

Exception Handler Breadth

ID Priority Requirement Related
CS-23-001 MUST NOT Code in vultron/ MUST NOT wrap domain logic in a blanket except Exception or a bare except:. The one sanctioned broad-catch boundary is a behavior-tree node's update() method, where converting an unexpected error into Status.FAILURE is the documented node contract (BT-HELPER-01). Any other broad catch is permitted only at a genuine framework or execution boundary, such as the BTBridge execution boundary or py_trees setup()/initialise().

A broad catch handles every error the same way, including defects nobody expected. In this codebase an undocumented broad catch more often hides a defect than handles a real case. The error then shows up later as a wrong result, far from its cause, or not at all.
CS-23-002 MUST An exception handler in vultron/ MUST catch the narrowest concrete exception types it can meaningfully handle. At a framework or execution boundary, that is the narrowest type that covers the boundary.

A narrow catch lets an unexpected error stop the work where it happens, so it surfaces loudly and is not silently absorbed.
Extends: CS-23-001
CS-23-003 MUST A broad catch at a framework or execution boundary MUST carry an inline comment that states what it guards and why.

The inline comment at a sanctioned boundary tells a reviewer what the catch is for, so a reviewer can tell a real boundary from a hidden defect.
Extends: CS-23-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

Module Placement and Config API

ID Priority Requirement Related
CFG-01-001 MUST The application MUST provide a top-level neutral package vultron/config/ whose app.py module contains AppConfig, get_config(), and reload_config().

Every layer needs the same settings. One neutral package gives core, wire, adapter and demo code one place to read them. Without it, each layer reads the environment in its own way, and two layers can disagree about the value of one setting.
CFG-01-002 MUST get_config() MUST return the same AppConfig instance on every call in one scope. Inside the scope of an app that holds its own config, that is the app's config. Otherwise it is the process-wide config, loaded once on first call and cached for all subsequent calls.

Code reads settings in many places, some of them on each request. A cached instance reads the file and the environment once, so all callers see the same values and no caller reads the file again. Several apps in one process each act as one node, so each app's work reads its own node's config, as a container does (ADR-0206).
CFG-01-003 MUST reload_config() MUST clear the cached instance so the next get_config() call re-reads configuration from the file and environment.

Tests and tools change environment variables while the process runs. Because get_config() caches its result, a changed variable has no effect until the cache is cleared. reload_config() gives callers one known way to clear the cache and load again.
CFG-01-004 MUST Code outside vultron/config/ MUST read Vultron application settings through get_config(), not through os.environ.get().

A direct environment read skips the YAML file, the field defaults and the field validators. A test that supplies a configuration file or overrides get_config() does not reach that code. One read path keeps the precedence and the validation the same for every setting.
CFG-01-005 MUST AppConfig MUST be injectable in FastAPI routers via Depends(get_config).

A router that receives AppConfig through Depends(get_config) does not read global state itself. A test can then give the router a different configuration through FastAPI dependency overrides, with no change to the environment.
CFG-01-006 MUST NOT vultron/config/ MUST NOT import from adapter-layer or FastAPI modules; it is a neutral shared module usable by all layers.

Core, wire and adapter code all import the configuration. If vultron/config/ imported an adapter or FastAPI module, core code would depend on the adapter layer through it, and import cycles between the layers would become likely.

Config File Format and Loading

ID Priority Requirement Related
CFG-02-001 MUST The application MUST support loading its configuration from a YAML file.

An operator needs one file that holds all settings for a node, in a format that people can read and edit.
CFG-02-008 MUST The application MUST use config.yaml in the project root as the default configuration file path. The project root is the current working directory at startup.

A fixed default path lets a node start with no extra arguments when the file is in the working directory.
Extends: CFG-02-001
CFG-02-002 MUST The default config file path MUST be overridable via the VULTRON_CONFIG environment variable.

One host can run more than one node, and a container can mount its file at any path. An environment variable lets each node select its own file with no code change and no change to the working directory.
CFG-02-003 MUST The application MUST use pydantic-settings (BaseSettings) with a custom YAML settings source to implement config loading.

pydantic-settings already gives typed fields, validation, environment variable parsing and source precedence. A custom YAML source adds the file to that system. A loader written by hand would have to do all of this again, and it could get the precedence wrong.
CFG-02-004 MUST When the YAML file and an environment variable both set a field, the application MUST use the environment variable value.

Container platforms and CI set environment variables for each deployment, while the file holds the shared values. When the environment wins, an operator can change one value for one deployment without an edit to the shared file. A fixed order also tells the reader which value is in effect.
CFG-02-006 MUST When VULTRON_CONFIG points to a file that does not exist, the application MUST raise a descriptive error at startup, not ignore the missing path.

When an operator sets VULTRON_CONFIG, the operator expects the node to use that file. If the node ignored a wrong path, it would start with defaults, and the operator could think that the file is in effect. An error at startup shows the mistake before the node does any work.
CFG-02-007 MUST If no config file exists at the default path and VULTRON_CONFIG is unset, the application MUST start using defaults only with no error.

The default path is a convenience, not a demand. A node with no file at the default path has no configuration error, so it starts with its defaults. Without this rule, every test and every first run would need a file that contains nothing.

Environment Variable Naming

ID Priority Requirement Related
CFG-03-001 MUST All Vultron application environment variables MUST use the VULTRON_ prefix.

AppConfig reads only variables that have this prefix, so a Vultron setting without it has no effect. One prefix also shows which variables belong to Vultron, and it prevents a collision with a variable of the same name that another tool on the host uses.
CFG-03-002 MUST Nested config section fields MUST use double-underscore (__) as the hierarchy separator, following pydantic-settings nested-model conventions (e.g., VULTRON_SERVER__BASE_URL, VULTRON_DATABASE__DB_URL).

Nested sections need a separator that cannot occur inside a field name. Field names use single underscores, so a double underscore is not ambiguous. It is also the separator that pydantic-settings uses, so no custom parsing is necessary.
CFG-03-003 MUST The following legacy environment variable names MUST be removed from all source files and replaced with their normalized equivalents: VULTRON_API_BASE_URL → VULTRON_SERVER__BASE_URL; DEVLOGS_DIR → VULTRON_DEVLOGS_DIR

An old name that stays in some files gives two names for one setting. An operator can then set one name while the code reads the other, and the setting has no effect. One normalized name for each setting prevents this.

AppConfig Structure

ID Priority Requirement Related
CFG-04-001 MUST AppConfig MUST have a server sub-section (a nested ServerConfig model) containing at minimum: base_url (str) and log_level (str).

The server needs its own base URL to create object IDs, and it needs a log level at startup. A separate section keeps these values together and gives them one shared prefix in the environment.
CFG-04-002 MUST AppConfig MUST have a database sub-section (a nested DatabaseConfig model) containing at minimum: db_url (str).

The storage location changes between a test, a demo and a deployment. A separate section keeps the storage settings apart from the server settings, so a new storage setting does not change another section.
CFG-04-003 MUST ServerConfig.base_url MUST default to "http://localhost:7999/api/v2".

Object IDs and actor IDs start with the base URL. A hosted actor's ID is {base_url}/actors/{slug}, and it must be the URL that reaches the actor. The API serves actors under /api/v2, so a default without that path creates IDs that reach nothing. This default matches the local port and the URL form that the compose files set.
CFG-04-004 MUST ServerConfig.log_level MUST default to "INFO".

INFO shows the lifecycle and state changes an operator follows, without the detail of DEBUG. A node with no log level setting then logs what an operator needs.
CFG-04-008 MUST ServerConfig MUST accept as log_level only DEBUG, INFO, WARNING, ERROR or CRITICAL, in any case on input, and store it in upper case.

A wrong log level name must stop the start with a clear error. A silent fallback to another level could hide the logs an operator needs, or fill the logs with detail. Case-insensitive input accepts the forms that operators type, and upper-case storage matches the names that the logging module uses.
CFG-04-005 MUST DatabaseConfig.db_url MUST default to "sqlite:///vultron.db".

A SQLite file in the working directory lets a node keep its data across restarts with no database server to install. This keeps the start with defaults only (CFG-02-005) useful, not only possible.
CFG-04-006 MUST NOT A field validator in the configuration models MUST NOT implement a cross-field business rule.

A rule that compares two fields is about how the node behaves, not about the form of a value. That rule belongs with the code that owns the behavior, where its tests are, and not in the configuration model.
CFG-04-009 MUST The configuration models MUST enforce per-field constraints, such as URL format and a valid log level name, in field validators.

Field validators run when the configuration loads, so they are the correct place to refuse a malformed value. A node then never starts with a value that it cannot use.
Constrains: CFG-04-008
CFG-04-007 MUST NOT AppConfig MUST NOT include seed actor or demo scenario configuration; those belong in SeedConfig.

Seed actors and demo scenarios exist only for demos and tests. If AppConfig held them, every production node would load and validate demo settings, and production code could start to depend on them. A separate SeedConfig keeps demo settings out of the production configuration.

SeedConfig Alignment

ID Priority Requirement Related
CFG-05-001 SHOULD SeedConfig (in vultron/demo/seed_config.py) SHOULD use pydantic-settings BaseSettings, as AppConfig does.

When both models load in the same way, a developer learns one set of rules for files, environment variables and precedence. A second loader written by hand could read the same variables in a different way.
CFG-05-002 MUST SeedConfig MUST remain a separate class and file from AppConfig; it is demo/seed tooling, not production config.

Seed settings change with each demo scenario, but production settings must stay stable. Separate classes and files keep a demo change out of the production model, and they let a production node run with no demo module loaded.
CFG-05-003 MUST SeedConfig env var names MUST use the VULTRON_ prefix (e.g., VULTRON_ACTOR_NAME, VULTRON_ACTOR_TYPE, VULTRON_ACTOR_ID, VULTRON_SEED_CONFIG).

Seed variables are set in the same environment as the other Vultron variables. The same prefix shows that they belong to Vultron, and it prevents a collision with the variables of other tools (CFG-03-001).

Testing

ID Priority Requirement Related
CFG-06-001 MUST Config loading MUST be testable using pytest's monkeypatch.setenv() to inject environment variable overrides without modifying the process environment permanently.

Tests must change configuration values without leaking them into later tests. monkeypatch.setenv() undoes each change when the test ends, so tests stay independent and can run in any order.
CFG-06-002 MUST Config loading MUST be testable using pytest's tmp_path fixture to supply a temporary YAML config file.

Tests of the YAML source need a real file. A file in tmp_path is unique to each test and pytest removes it later, so a test does not change the project's own config.yaml and does not depend on it.
CFG-06-003 MUST Test fixtures MUST clear the config cache between test cases by calling clear_config_cache() (which drops the cached config without loading a new one) in teardown — NOT by calling reload_config(). Calling reload_config() in teardown triggers an immediate cache reload before pytest's monkeypatch reverts environment-variable changes, which locks in the test's environment state for the reload and pollutes the next test. Clearing the cache defers the reload until the next get_config() call, by which time monkeypatch has already restored the environment.

reload_config() loads the configuration again at once. In teardown, the test's environment changes are still in force, so that reload puts the test's values in the cache, and the next test starts with them. clear_config_cache() only drops the cache. The next get_config() call then loads after monkeypatch has restored the environment.
CFG-06-004 MUST Tests MUST verify that environment variables override YAML values for the same field.

Environment-over-file precedence (CFG-02-004) lets an operator change one value for each deployment. If a change to the source order reversed it, the node would use the file value and give no error. A test shows that reversal when it occurs.
CFG-06-005 MUST Tests MUST verify that the application starts successfully with all defaults (no file, no env vars set).

Every test and every first run depends on a start with defaults only (CFG-02-005). A new field with no default, or a default that fails validation, would stop that start. A test finds this before a user does.
CFG-06-006 MUST vultron/config/app.py MUST export a config_override(**env_updates) context manager. On entry it atomically sets the given environment variables, calls reload_config() and yields the updated AppConfig. On exit it restores the original values and calls reload_config() again.

If a fixture reloads the configuration before it restores the environment, the cache keeps the test's values for later tests. config_override() changes the environment, reloads and restores in the correct order in one place.
CFG-06-008 MUST config_override() MUST restore the environment and reload the configuration in a finally block, so the restore also runs when the body raises.

A test that fails inside the body raises an exception. The finally block restores the environment and the cache then too, so a failed test does not change the next test.
Refines: CFG-06-006
CFG-06-007 SHOULD A test fixture that overrides AppConfig values SHOULD use config_override(), not monkeypatch.setenv() with explicit reload_config() calls.

With config_override() (CFG-06-006), a fixture cannot put the restore and the reload in the wrong order.
CFG-06-009 MUST A fixture that uses monkeypatch directly, such as a session-scoped fixture, MUST call monkeypatch.undo() before any reload_config() call in teardown.

Some fixtures cannot use config_override(), for example session-scoped fixtures that use monkeypatch directly. Those fixtures must undo the environment changes before they reload, or the cache keeps the test's values (CFG-06-003).

Actor Configuration

ID Priority Requirement Related
CFG-07-001 MUST A neutral ActorConfig Pydantic model MUST be defined outside the demo layer (e.g., in vultron/core/models/ or vultron/config/actor.py) so it can be used by BT nodes, API adapters, and CLI entry points without importing from vultron/demo/.

BT nodes, API adapters and CLI entry points all need the local actor's policy, for example its default CVD roles. BT nodes must not import from the demo layer (BTND-04-002), and demo code is not part of a production node. A neutral ActorConfig gives all of them that policy with no import from vultron/demo/.
CFG-07-002 MUST ActorConfig MUST include a default_case_roles field of type list[CVDRoles], defaulting to an empty list, representing the CVD roles the local actor assumes when creating or owning a VulnerabilityCase.

The local actor states its CVD roles on the case proposal, and its participant record carries them. These roles are a fact about the actor, so they come from its configuration and are not inferred (CP-09-008). An empty default is safe, because the Case Owner role is added when the participant record is created.
CFG-07-004 MUST BT nodes that create a Case Owner participant record for the local actor MUST source the actor's CVD roles from ActorConfig.default_case_roles, not from a hardcoded constant.

A hardcoded constant would give every node the same roles. A Vendor, a Coordinator and a Reporter have different roles in a case, and the participant record must show the roles that the operator set for this actor.
CFG-07-005 MUST A load_actor_config() function MUST exist in vultron/config/ (the neutral config sub-package).

Production adapters need the local actor's policy. If they loaded it from the demo SeedConfig, the demo layer would become a dependency of every production node. load_actor_config() in the neutral vultron/config/ package gives them the policy from AppConfig, with no demo import.
CFG-07-006 MUST CVDRole and its helpers serialize_roles and validate_roles MUST reside in the neutral enum module vultron/enums/roles.py, not in vultron/core/.

vultron/config/ must not import from vultron/core/, but ActorConfig needs CVDRole to type its roles field. A neutral enum module that every layer can import lets config, core and adapter code use one CVDRole, with no import from core and no import cycle.
CFG-07-007 MUST LocalActorConfig in vultron/demo/seed_config.py MUST be decoupled from ActorConfig.

Identity data and actor policy have different lifecycles. Identity seeds the DataLayer once at startup. Policy comes from AppConfig.actor each time a behavior needs it. If one model held both, demo seed code could change production policy, and a policy change could need a new seed file.
CFG-07-009 MUST load_actor_config() MUST return the ActorConfig that get_config() holds in AppConfig.actor.

Actor policy must use the same file, environment variables and precedence as every other setting. If load_actor_config() read its own sources, its result could differ from the actor section that get_config() returns. A test that changes the configuration would then not reach the actor policy.
CFG-07-010 MUST Production adapter modules MUST import load_actor_config() from vultron/config/ rather than importing from vultron/demo/ to obtain actor policy configuration.

A production adapter that imports from vultron/demo/ makes the demo layer part of every production node. Demo code can then change production behavior, and a deployment cannot leave the demo layer out. The neutral load_actor_config() gives the adapter the same policy with no demo import.
CFG-07-011 MUST LocalActorConfig MUST carry only demo/bootstrap fields (name, actor_type, id_).

LocalActorConfig exists only to seed the actor record with a name, a type and an ID. A policy field in it would be a second source for that policy beside AppConfig.actor, and the two sources could disagree.
CFG-07-012 MUST NOT LocalActorConfig MUST NOT extend ActorConfig; actor policy fields (auto_create_case, default_case_roles) belong in AppConfig.actor and are loaded via load_actor_config().

Extending ActorConfig entangles bootstrap identity with runtime actor policy, violating the distinct lifecycle separation described in CFG-07-007.

CVD Case State Behavioral Requirements

Event-Condition-Action behavioral requirements for CVD Case State (CS) transitions. Each group is triggered by either a received CS message or a local CS state transition, and specifies typed preconditions, ordered steps, and postconditions that implementations must satisfy. CS cascade chains that trigger embargo teardown reference EM behavior directly and are developed in concert with the EM behavioral requirements.

File ID: CSB

Trigger-Side VFD Role Preconditions

Precondition requirements for self-reported CS trigger endpoints (notify-fix-ready, notify-fix-deployed, notify-published). These complement the receive-side CSB-02, CSB-03, and CSB-04 groups by specifying which CVD roles may initiate each VFD transition locally and what state each trigger endpoint MUST set.

ID Priority Requirement Related
CSB-15-005 MUST This codebase MUST refuse a fix-ready transition (CSB-15-001) from an actor whose recorded case roles lack VENDOR. It refuses in the trigger tree, before it writes anything.

The status a sender builds only claims roles; the case records which roles the sender holds. The trigger guard judges the sender by the roles the case records, which is the authority for roles.
Implements: CSB-15-001
CSB-15-008 MUST NOT The participant status model MUST NOT itself reject a stray vf dimension.

A raise when the status is built would judge a sender by the roles its status claims. The trigger guard (CSB-15-005) and the receive path's refusal of a whole status (RSH-09-003) judge it by the roles the case records, which is the authority for roles.
Extends: CSB-15-005
CSB-15-006 MUST This codebase MUST refuse any deployer-path (d) assertion (CSB-15-002) from an actor whose recorded case roles lack DEPLOYER. It refuses in the trigger tree, before it writes anything.

A non-Deployer that asserts the not-deployed state d still claims a dimension it does not have. If the gate covered only D, such a participant could still write the deployer dimension, and readers would treat it as a deployer. The gate therefore covers d as well as D.
Implements: CSB-15-002
CSB-15-010 MUST NOT The participant status model MUST NOT itself reject a stray d dimension.

The reason is the one CSB-15-008 gives for vf: the model sees only the roles a status claims, while the trigger guard (CSB-15-006) and the receive path judge the sender by the roles the case records.
Extends: CSB-15-006

CS Write-Boundary Transition Validation

Requirements for CS state write paths (VFD and PXA) to validate source→target transition validity before persisting a ParticipantStatus snapshot. Complements CSB-15 (trigger-side role preconditions) and SDO-02-002 (dimension object transition contract) by requiring that the BT write node itself is fail-closed regardless of upstream guard coverage.

ID Priority Requirement Related
CSB-16-003 MUST This codebase MUST validate a local vf or d write (CSB-16-001) at the write boundary, not only in upstream guards. The write boundary is the BT node or helper that writes the participant status. The received path's weaker forward-only check is out of scope.

A guard can be too weak, missing or bypassed, and then an invalid jump reaches the write node. A check at the write boundary fails closed whatever the guards cover, so no invalid vf or d state reaches the store.
Implements: CSB-16-001
CSB-16-006 MUST An illegal local vf or d transition (CSB-16-003) MUST make the write node return Status.FAILURE, or the helper raise, without writing to the DataLayer.

A refusal that still wrote part of the status would leave an invalid vf or d state in the store. Failing before the write keeps the store at its prior state.
Extends: CSB-16-003
CSB-16-004 MUST This codebase MUST validate a local PXA write (CSB-16-002) at the write boundary. The write boundary is the BT node or helper that writes the case or participant status.

The guards can miss a backward PXA move, as they can miss a vf or d jump (CSB-16-003). A check at the write boundary catches it whatever the guards cover.
Implements: CSB-16-002
CSB-16-008 MUST A backward local PXA move (CSB-16-004) MUST make the write node return Status.FAILURE, or the helper raise, without writing to the DataLayer.

A backward PXA move would say that public awareness, a public exploit or observed attacks are no longer true, which cannot happen. The write boundary refuses it and persists nothing, so the store never holds a backward PXA state.
Extends: CSB-16-004

CSAF Documents in Reports

Requirements for a Common Security Advisory Framework (CSAF) 2.1 document that travels as an attachment of a VulnerabilityReport: how it is carried and recognized, the one occasion on which a receiver may read it as the sender's statement (the initial Offer of a report), how its fields map onto the inputs of the case created from that report, and how this codebase checks documents against a CSAF 2.1 draft that is still changing. Producing a CSAF document from a case (a projection) is out of scope (#5134).

File ID: CSAF

Receiving and Sending CSAF in This Codebase

ID Priority Requirement Related
CSAF-04-001 MUST This codebase MUST check each attached CSAF 2.1 document against the full CSAF 2.1 schema at receipt, and record a verdict of schema-valid or schema-invalid with each schema error.

The receiver wants to know at receipt whether the document holds together, and the errors tell its human what is wrong.
CSAF-04-002 MUST NOT The verdict of CSAF-04-001 MUST NOT call a document valid CSAF.

CSAF validity also needs the mandatory tests of the CSAF draft, which a schema cannot express. Measured against the test documents of the CSAF Technical Committee, the schema catches few of the documents that fail a mandatory test.
Extends: CSAF-04-001
CSAF-04-003 MUST This codebase MUST read the fields of CSAF-03 from a schema-invalid document one field at a time, skip each field it cannot read, and log each skipped field at INFO.

A fault in one part of a document says nothing about the rest of it, and CSAF-02-006 keeps the report itself.
CSAF-04-004 MUST This codebase MUST store with each received report that has a CSAF attachment the verdict, each value it read, and what became of each value: applied, overridden by a Vultron field, or kept for display only.

A human who validates the report sees what the document claimed and which claims shaped the case. Fields that set no case input, such as the TLP label, involvement and acknowledgments, are kept for that display. A case records no public credit, so acknowledgments stays display only (ADR-0218).
CSAF-04-005 MUST NOT This codebase MUST NOT send the record of CSAF-04-004 to another actor.

The record is the receiver's own judgment. Each actor that receives the report forms its own.
Extends: CSAF-04-004
CSAF-04-006 MUST This codebase MUST record a case-split signal with the report when the vulnerabilities of its CSAF document differ in public status, in P, X or A, or in their future disclosure dates.

One case takes the most cautious value (CSAF-03-002 to CSAF-03-005), which can hold back a vulnerability whose state differs. The Case Owner decides whether to split the case.
CSAF-04-007 MUST This codebase MUST record a candidate-parties signal with the report when the vendors of the products that its CSAF document lists as known affected are more than one, or include a vendor whose name differs from the receiving actor's name.

Affected products name the parties that a case needs, for example when a coordinator or one of several vendors receives the report. Party discovery then suggests those actors to the case (BT-20-003). A vendor name becomes an actor only through a directory that does not exist yet, so the receiver's own name is the one comparison that needs none.
CSAF-04-008 MUST NOT This codebase MUST NOT split a case, suggest an actor or invite an actor because of a signal of CSAF-04-006 or CSAF-04-007.

A split and an invitation are decisions of the Case Owner. A signal only shows that one may be needed.
Extends: CSAF-04-006
Extends: CSAF-04-007
CSAF-04-009 MUST The submit-report trigger MUST refuse, with HTTP 422 naming each fault, a CSAF document that fails the CSAF 2.1 schema or whose category is not csaf_vulnerability_report.

This is the sender's side of CSAF-02-007. A refusal that names each fault tells the Reporter what to correct before anything is sent.
CSAF-04-010 MUST The submit-report trigger MUST fill a report name, a report summary or a proposedEmbargo that its request leaves unstated from the attached CSAF document, by the mapping of CSAF-03 measured against the time it sends the Offer.

This is the sender's side of CSAF-02-004, so a receiver gets explicit Vultron fields and needs to read the CSAF document only for what they omit.

Following the CSAF 2.1 Draft

ID Priority Requirement Related
CSAF-05-001 MUST This codebase MUST check CSAF documents against one pinned revision of the CSAF 2.1 draft, recorded once with its source repository, commit and draft stage.

Every CSAF 2.1 draft uses the same $schema value, so a document cannot say which draft it follows. The crosswalk pages, the pinned local copy of the schemas and the models generated from them read the one record, so they cannot disagree about the draft.
CSAF-05-002 MUST This codebase MUST keep a pinned local copy of the CSAF 2.1 schema and of the schemas it references, and generate its CSAF models from that copy.

The CSAF schema references the CVSS and SSVC schemas by URL. A local copy makes the models reproducible without network access.
CSAF-05-003 MUST A test MUST fail when regenerating the CSAF models from the pinned local copy does not reproduce the committed models.

Without the test, a hand edit or a schema change without regeneration leaves the models out of step with the schema they claim to follow.
CSAF-05-004 MUST NOT The test suite MUST NOT depend on the test documents of the CSAF Technical Committee.

Those documents are governed by the OASIS IPR policy and change with the draft. An optional script that reads a local clone checks them when the pin moves.

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

Auto-Rehydration on Read

ID Priority Requirement Related
DL-01-001 MUST dl.read(id) MUST return a fully rehydrated, typed domain object: a Pydantic model instance whose dehydrated ID-string fields are expanded to their full typed objects.

Core use cases must not contain coercion logic for storage artefacts. See vultron/core/ports/AGENTS.md 'Auto-Rehydration'.
DL-01-005 MUST dl.read(id) MUST raise VultronNotFoundError when no object with that id exists.

A caller must be able to tell a missing object from a stored one. A named domain error lets core handle the missing case on purpose. A None result would let a caller go on with no object and fail later, far from the cause.
Extends: DL-01-001
DL-01-002 MUST dl.list(type_key) MUST return an iterable of fully rehydrated, typed domain objects.

Core code reads lists as often as it reads single objects. If list returned storage records while read returned domain objects, core would need two ways to handle stored data.
DL-01-006 MUST dl.list(type_key) MUST return an empty result, not raise an error, when no object of that type exists.

An empty result is a normal answer, not a fault. A caller then needs no error handling for a type that has no objects yet.
Extends: DL-01-002
DL-01-003 MUST The adapter MUST rehydrate every field it dehydrates on write, including object_, target and origin.

A field that is dehydrated on write but not rehydrated on read reaches core as a bare ID string. Core then needs coercion code, which DL-01-004 forbids.
DL-01-007 MUST When a dehydrated field references an ID with no stored object, the adapter MUST log a WARNING and return the ID string as it is.

Preserves partial readability when nested objects are deleted.
Extends: DL-01-003
DL-01-004 MUST Core use cases MUST NOT contain manual coercion of dl.read() results; specifically, model_validate on a dl.read() result, record_to_object() calls, and isinstance(result, Document) checks are prohibited in vultron/core/.

These patterns indicate the adapter is not satisfying its rehydration contract and MUST be fixed in the adapter, not in core.

Type-Safe Write Operations

ID Priority Requirement Related
DL-02-001 MUST dl.save(obj) MUST accept a typed Pydantic domain object directly and do all serialisation and dehydration itself.

Keeps serialisation concerns inside the adapter layer.
DL-02-005 MUST NOT Core code MUST NOT call object_to_record() before it passes an object to dl.save().

Conversion to a storage record is the adapter's work (DL-02-001). If core converts first, core depends on the storage format, and a change to that format must also change core.
Extends: DL-02-001
DL-02-002 MUST dl.save(obj) MUST be idempotent by the object's id_: a second save of the same object leaves the stored state that one save gives (upsert semantics).

Idempotent writes prevent duplicate-key errors in retry scenarios.
DL-02-003 MUST dl.save_if_unchanged(obj, expected) MUST write obj, atomically with the check, only if the stored record with that id still equals expected in stored form.

A read-modify-write through dl.save() overwrites any write that lands between the read and the save, and nothing reports the lost write. A compare-and-set closes that gap without a schema change. The caller decides what a refusal means: EP-02-008, for example, reads the record again and applies its change again. See notes/datalayer-design.md.
DL-02-006 MUST dl.save_if_unchanged(obj, expected) MUST return False and write nothing when the stored record differs from expected or no record with that id is stored.

A refused compare-and-set must leave the store as it was, so the write that landed first survives. A False result tells the caller to read again, instead of an exception it must catch. An absent record is a changed record: the caller's view of the store is stale either way.
Extends: DL-02-003
DL-02-007 MUST dl.save_if_unchanged(obj, expected) MUST raise ValueError when the id of obj differs from the id of expected.

A replacement for a different record is a caller defect, not a lost race. If the call returned False, the caller would read again and retry forever.
Extends: DL-02-003
DL-02-004 MUST with dl.transaction(): MUST make every call on that store, from the thread that opened the block, one atomic unit. Every write inside the block commits when it ends, or none does when it raises.

An act and its consequences are several DataLayer calls (an activity, an outbox row, ledger entries, the case-file save). Committed one call at a time, a failure part-way leaves a state no single act produces, and recovery machinery to finish it is what ADR-0146 rejects.
DL-02-008 MUST A read inside a dl.transaction() block MUST see the block's own writes.

An act often reads what it has just written, such as a case it saved before it queues a reply. save_many is atomic only within one call, and its callers cannot read their own uncommitted writes.
Extends: DL-02-004
DL-02-009 MUST A dl.transaction() block opened inside another MUST roll back only its own writes when it raises.

A helper that opens its own block can fail while its caller goes on. If the inner failure undid the caller's writes too, the caller would continue on a state it did not write.
Extends: DL-02-004
DL-02-010 MUST A side effect that tells another component a write happened, such as the outbox enqueue callback, MUST run only after the dl.transaction() block commits.

If the callback ran before the commit, a delivery worker could look for an outbox row that a rollback then removes. The other component must hear only of writes that exist.
Extends: DL-02-004
DL-02-011 SHOULD Inside a dl.transaction() block, a read of a record the block already read SHOULD NOT fetch it from the store again unless, in between, the block wrote that record or rolled back an inner block.

One act reads the same few records hundreds of times, such as its case and the case's participants (#5344). Inside a block nothing but the block's own writes can change the store, because the block holds the write lock, so a record it read stays current until it writes that record. A read after a write, or after an inner block that rolled back, still returns what the store holds (DL-02-008).
Extends: DL-02-008

Port Isolation

ID Priority Requirement Related
DL-03-001 MUST The DataLayer port (vultron/core/ports/datalayer.py) MUST be defined entirely in terms of core domain types.

Enforces hexagonal architecture layer separation (ARCH-01-001).
Derives from: ARCH-01-001
DL-03-003 MUST NOT The DataLayer port MUST NOT import from vultron/wire/, vultron/adapters/, or any storage-specific library, such as SQLModel or TinyDB.

An import from the wire layer, an adapter or a storage library ties core to that code. A change of wire format or storage engine would then change the port, and core could not be tested with a mock adapter (ARCH-01-001).
Extends: DL-03-001
DL-03-002 MUST The DataLayer adapter MUST NOT expose vocabulary registry lookups or AS2 type-name resolution to core; the vocabulary registry is a wire-layer concern and the adapter must maintain its own internal mapping.

Prevents wire-layer types from leaking into the core domain through the persistence port.

Narrow Core Persistence Ports

ID Priority Requirement Related
DL-04-001 MUST Core use cases and BT nodes MUST depend on CasePersistence or CaseOutboxPersistence, not on the full DataLayer port. Only a documented exception permits the broader interface.

A narrow, intention-revealing port as the default dependency shows a reader what core can do with storage, and keeps adapter-only operations out of core.
DL-04-006 MUST The DataLayer port MUST remain the full adapter-level persistence contract.

Adapters and infrastructure code need queue, admin and diagnostic operations that core must not see (DL-04-003). One complete contract gives every adapter a single interface to implement, and the narrow ports are subsets of it.
Extends: DL-04-001
DL-04-002 MUST CasePersistence MUST declare at least the core-facing persistence surface. That surface is actor_id, clone_for_actor, create, read, read_case, save, save_many, transaction, list_objects, find_case_by_report_id, find_actor_by_short_id, find_case_by_short_id, find_protocol_pair and delete.

A narrow port lets a reader see what core can do with storage. The list states the Protocol in vultron/core/ports/case_persistence.py; a difference is a spec defect. actor_id and clone_for_actor are in it because each store belongs to one actor (DL-07-002) and reaching another's must be named (DL-07-005). read_case gives a typed case read, so callers do not narrow a read() result. A new query helper may join it if it keeps to domain persistence (DL-04-003).
DL-04-003 MUST NOT CasePersistence MUST NOT include inbox queue methods, outbox inspection or drain methods, ping, clear_*, update, get_all, all, count_all, or other infrastructure, admin, or diagnostic operations that belong to the full DataLayer adapter contract.

Queue, admin and diagnostic operations work on storage, not on case data. If core can call them, core logic starts to depend on how the adapter stores data. delete is not on this list: core removes records that it wrote itself, and that is a domain operation (DL-04-002). update is on this list because core changes a record through save, which is idempotent by object id (DL-02-002).
DL-04-004 MUST CaseOutboxPersistence MUST extend CasePersistence only with the outbound queue's methods outbox_append and outbox_list.

A reader of a use case must see that it sends, and a separate port shows it in the type. Both methods work on the outbox of the actor that owns the store: outbox_append queues an activity, and outbox_list reads which are pending. Neither takes an actor id, since that would allow a write to the queue of another actor (DL-07-001). A received tree emits through this port in its effects stage (ADR-0214).
DL-04-005 MUST NOT get() and by_type() MUST NOT be declared on CasePersistence.

get and by_type return raw storage records, not typed domain objects. A raw record in core brings back the coercion code that DL-01-004 forbids. Neither method is on the Protocol now, and this rule keeps them out.
DL-04-008 MUST Core code MUST read stored objects through the typed read(), list_objects() or dedicated typed helper methods.

Typed reads return domain objects, so core needs no coercion code (DL-01-004) and static analysis sees the real type.
Extends: DL-04-005
DL-04-009 MUST A change that adds a raw-record method to CasePersistence MUST record that addition as a deliberate decision.

A real need for raw access can arise. It must be a recorded decision, so that nobody adds a raw-record escape hatch by accident.
Extends: DL-04-005

Core-Object Read Contract

The DataLayer read path MUST return core domain objects for every persisted type that has a registered core counterpart. Wire-layer vocabulary types MUST NOT be handed to core code through the persistence port.

ID Priority Requirement Related
DL-05-001 MUST dl.read(id) and dl.list_objects(type_key) MUST reconstruct persisted domain entities using the core vocabulary registry (vultron.core.models.registry.CORE_VOCABULARY) so that the returned instance is a vultron.core.models type (e.g. core VulnerabilityCase), never a vultron.wire.as2.vocab type (e.g. as_VulnerabilityCase), whenever the persisted type_ has a registered core counterpart.

Core code MUST receive core domain objects so that core validators run and static analysis sees the real type (ARCH-01-002). Reconstructing via the wire VOCABULARY returns wire objects that only work in core by structural coincidence of field names. Decided in ADR-0034; derived from ARCH-01-002 and DL-03-002.
Derives from: ARCH-01-002
DL-05-002 MUST The DataLayer adapter MUST own the wire↔core translation for persistence.

The wire registry is a wire-layer concern (DL-03-002). Making the adapter own translation decouples DataLayer storage from the wire type system so the wire layer can evolve without breaking persistence.
Implements: DL-03-002
DL-05-003 MUST NOT Core code (vultron/core/) MUST NOT use structural duck-typing Protocols to accept DataLayer results in place of concrete core types.

The duck-typing Protocols exist solely to let core touch wire objects at runtime without a compile-time wire import, evading rather than honouring ARCH-01-001. When the read path returns core objects, the Protocols are dead weight and mask the boundary from mypy/pyright.
Refines: ARCH-01-002
DL-05-010 MUST Core code MUST depend on concrete core domain classes for DataLayer results and narrow them with isinstance.

A concrete class lets mypy and pyright check each use of a stored object. isinstance narrowing then states in the code which type core expects.
Extends: DL-05-003
DL-05-004 MUST An architecture ratchet test MUST assert that dl.read() and dl.list_objects() return no vultron.wire.as2 vocabulary type into vultron/core/.

Prevents regression back to wire-object leakage into core.
DL-05-011 MAY The DL-05-004 ratchet test MAY exempt a persisted AS2 Activity type that has no registered core counterpart.

Core still reads some activities back, and that read-back is a boundary violation tracked on its own (DL-06-001). The exemption lets the ratchet guard every other type while that work is open.
Supersedes: DL-05-004
DL-05-012 MUST The DL-05-004 ratchet test MUST list each exempt type explicitly, so that the exemption set can only shrink.

An explicit list documents the remaining debt and ratchets toward zero. A rule that exempts by category would admit each new activity type without review.
Extends: DL-05-004
DL-05-005 MUST The persistence write path MUST normalise wire to core through a CORE_VOCABULARY lookup (DL-05-006, ARCH-23-002), not through a hand-kept list of wire classes in vultron/adapters/driven/db_record/.

A wire-shaped row in a core-typed table breaks every later read of that row. A hand-kept list of wire classes to normalise must change each time a type changes, and a missed update is a silent defect. The CORE_VOCABULARY lookup needs no list.
Implements: DL-05-001
Uses definition from: DL-05-006
See also: ARCH-23-002 — context for the reader
DL-05-013 MUST NOT This codebase MUST NOT keep a _NORMALIZE_WIRE_TO_CORE list or a ratchet test over it.

Wire and core registry keys are disjoint (ARCH-23-002), so no wire class can shadow a core type, and the list is always empty. A check over an empty list can never fail. It gives false confidence, so the list and its test must not exist (ADR-0211).
Refines: DL-05-005
Depends on: ARCH-23-002 — Disjoint registry keys are what empty the list.
DL-05-006 MUST The DataLayer adapter MUST maintain its own type_→core-class mapping (via CORE_VOCABULARY) that is independent of the wire VOCABULARY registry.

An independent adapter-owned mapping decouples DataLayer storage from the wire type system so the wire layer can evolve without breaking persistence (DL-03-002).
DL-05-007 MUST NOT The wire vocabulary registry MUST NOT be the mechanism by which core objects are reconstructed on the DataLayer read path.

Using the wire registry for core object reconstruction leaks wire-layer concerns into the adapter read path, violating DL-03-002.
DL-05-008 MUST NOT The persistence write path MUST NOT keep a deferral list of types not yet normalised, such as _NOT_YET_NORMALIZED in vultron/adapters/driven/db_record/.

With disjoint registry keys (ARCH-23-002), no wire type shadows a core type, so no type is left to defer. extra="forbid" (ARCH-12-003) makes a wrongly shaped row fail at read-back. An empty deferral list in the source code invites a contributor to add the next entry to it, instead of a fix to the type.
Derives from: DL-05-005 — The deferral list has no purpose once the normalisation list it defers against is gone.
DL-05-009 MUST The closed-form guarantee that no wire-shaped row slips into a core-typed table MUST be carried by the structural invariants — disjoint registry keys (ARCH-23-002) plus extra="forbid" on every core-branch type (ARCH-12-003) — rather than by a per-type coverage ratchet over _NORMALIZE_WIRE_TO_CORE.

A coverage check over a list protects only the types that somebody put on the list. A new type that is not on the list is a silent gap. Disjoint registry keys make a shadowing type impossible to create. extra="forbid" makes an un-normalised row raise an error, so its keys are not silently dropped. The type system holds these two properties, so nobody has to maintain a list.
Depends on: ARCH-12-003 — extra="forbid" is the read-back guard that replaces per-type coverage bookkeeping.
Depends on: ARCH-23-002

Activity Read-Back and the Semantic/Envelope Split

Core code MUST NOT read a persisted wire AS2 Activity back from the DataLayer to recover its semantic content. AS2 protocol Activities are wire-only envelopes with no registered core counterpart (the DL-05-004 exemption set); the domain fact each carries MUST live as core state. A received activity is archived as the body that arrived, and two reads of it are sanctioned: core reads its facts from the read-only view a load of that body yields, and a wire/adapter-owned seam parses it to embed it in a reply. Decided in ADR-0035, partially superseded by ADR-0149; extends DL-05 and ARCH-09-001.

ID Priority Requirement Related
DL-06-001 MUST NOT Core code (vultron/core/) MUST NOT call dl.read(activity_id) or dl.list_objects(<activity_type>) to recover the semantic content of a persisted wire AS2 Activity.

AS2 protocol activities have no core counterpart. If core reads one back, core receives a vultron.wire.as2 type (ARCH-01-002). Core also interprets again an activity that the semantic extractor already interpreted (ARCH-03-001). The stored activity then becomes the record of a domain fact, but wire must be a projection of core (ARCH-09-001). Examples are a read of a stored Offer to get the embedded report, or of a stored Invite to get its case or embargo id. See ADR-0035.
Derives from: ARCH-03-001
DL-06-007 MUST Core code MUST read a received activity's facts only from the read-only view that a load of its archived body yields (the ReceivedActivityLoader port).

The loaded view is the output of the semantic extractor for the archived body. It interprets nothing again and gives core no wire type, so it is the one sanctioned way for core to read a received activity (ADR-0149).
Extends: DL-06-001
DL-06-008 MUST Core code MUST read every domain fact other than a received activity's own facts from core state.

Core is the system of record for domain facts (DL-06-002). A fact read from anywhere else, such as a stored wire activity, can differ from what core holds.
Extends: DL-06-001
DL-06-002 MUST Core code MUST store each domain fact an actor keeps from a received protocol message as core state, when the semantic extractor first interprets it. That core state is a state transition on an existing core entity or a purpose-built core record.

Core is the sole system of record for domain facts (the Actor Knowledge Model bounds an actor's knowledge to what it has received, and that knowledge is held as core state). Capturing the fact once at extraction time removes the need for core to reach back through the wire envelope. This does NOT mean cloning each AS2 Activity into a 1:1 core Activity class; model only the domain fact each message conveys, in domain vocabulary, capturing only what handlers use. Decided in ADR-0035.
Derives from: ARCH-03-001
DL-06-009 MUST NOT Core code MUST NOT rebuild such a fact later by reading a stored activity again. A read of the view a received activity's archive loads (DL-06-007) is not such a re-read.

A fact rebuilt from a stored envelope depends on the envelope surviving as a semantic record, and interprets the activity a second time. The archive's loaded view is the extraction itself, run again on the archived body, so reading it reaches back through no envelope (ADR-0149).
Extends: DL-06-002
See also: DL-06-007 — context for the reader
DL-06-003 MUST When an inbound protocol message references a prior message (e.g. an Accept answering an Invite, a counter-offer answering an Offer), core MUST correlate them through a core-entity relationship (e.g. "the pending embargo proposal for this case", "the invitation for this actor"), NOT by re-reading the referenced wire activity from the DataLayer.

Correlation is a domain relationship between core facts. Recovering it by re-reading the referenced activity reintroduces the DL-06-001 violation and depends on the wire envelope surviving as a semantic record. When the prior message was first received it MUST have created or updated the core entity that the later message now correlates to. Decided in ADR-0035.
DL-06-004 MUST When an outbound reply carries the original activity inline in object_ or in_reply_to, the wire/adapter layer MUST rebuild it from the body the receiver archived. This seam is not a core boundary violation under DL-05-004.

Activity IDs are non-regenerable random urn:uuid: values and the Actor Knowledge Model requires a reply to embed the full inline original activity, so verbatim reconstitution cannot be produced by re-projecting core state. The original envelope, with its original id, must be kept and read back. A wire/adapter seam for that read keeps semantic authority in core (ADR-0035).
See also: DL-05-004 — scope boundary of the ratchet, not a case of it
DL-06-010 MUST A reply that embeds a received activity MUST embed the archived body as it was received, with every key it holds.

A re-dump of a parsed or extracted form is not the original: the parse sets aside keys the vocabulary does not name, and the extractor keeps only what core reads. Only the archived body itself is the activity the sender sent (ADR-0149).
Extends: DL-06-004
DL-06-011 MUST NOT Core code MUST NOT read the archived body that a reply embeds to interpret its meaning.

The embedding seam carries the body for transport only. If core interpreted it, the stored envelope would become a semantic record again, which DL-06-001 forbids.
Extends: DL-06-004
DL-06-005 MUST When a core semantic read moves off activity read-back (DL-06-001 to DL-06-003), this codebase MUST remove its activity type from the DL-05-004 exemption set.

The exemption set names the AS2 activity types that dl.read() may still return to core. When a core read moves off activity read-back, its type leaves the set, so the set shows the work that remains. A test fails when an exempt type gets a core counterpart, so a stale entry cannot stay in the set. See ADR-0035.
Extends: DL-05-012
Uses definition from: DL-06-001
See also: DL-05-004 — context for the reader
See also: DL-06-003 — context for the reader
DL-06-012 MUST The DL-05-004 exemption set MUST be empty once every core semantic activity read has moved off activity read-back.

When the set is empty, no core semantic read of an activity is left (DL-06-001). The only sanctioned activity reads that remain are the wire/adapter seam of DL-06-004 and core's reads of an archive's loaded view (DL-06-007), and neither needs an exemption.
Extends: DL-06-005
See also: DL-05-004 — context for the reader
DL-06-006 MUST NOT A receiver MUST NOT hold a received activity in its DataLayer as a record readable by the id the sender chose for it, at any stage: not at inbox ingress, not for a deferred replay, and not in a received-side tree. A received activity is held only under one key the receiver derives from the activity id, ReceivedActivityRecord.build_id, whichever stage the record is in: archived, held for a replay the inbox still owes (IO-03-009), or reduced to the receipt stub a refusal left (CLP-10-018). A record of an activity type stored under its own id is then always one the receiver authored.

An actor scans the type tables of its sent activities to answer "did I already send this?". For example, it checks whether it announced a case or which stub Invites it issued. A received copy stored under the sender's id gives a false yes, also when its unsigned actor field names the receiver. CLP-10-017 keeps intake off the sender's id for this reason. This rule gives the same protection at every writer, so a received activity never looks like one that the receiver sent.
Uses definition from: IO-03-009
See also: CLP-10-018 — names the third stage a record can be in; what a refusal leaves is not a narrower case of keeping a received activity off the sender's id

Per-Actor Store Isolation

ID Priority Requirement Related
DL-07-001 MUST Each actor MUST have its own store.

CM-01-001 requires that the data of one actor is isolated from the data of another. If isolation depends on a filter column in each query, reads are separated but writes are not. A save() by one actor can then overwrite the row of another actor, and a create() can fail for a second actor that holds its own replica of the same object. When each actor has its own store, the layout carries the isolation, and these failures cannot occur. See ADR-0073.
Implements: CM-01-001
DL-07-015 MUST A DataLayer instance MUST belong to exactly one actor.

An instance that serves two actors can read and write the data of both. One actor per instance makes the instance itself the isolation boundary.
Extends: DL-07-001
DL-07-016 MUST NOT A write by one actor MUST NOT change what another actor can read, including a write to an object ID that both actors hold.

Read isolation alone does not stop a write by one actor from overwriting the row of another. Two actors often hold their own replica of the same case, so the same object ID is the common case, not an edge case.
Extends: DL-07-001
DL-07-017 MAY Two actors MAY each hold their own replica of the same object ID.

Each participant keeps its own replica of a case and its objects, under the ids the CASE_MANAGER gave them. A store that refused a second copy of an id would stop a second participant from holding the case.
DL-07-002 MUST NOT A DataLayer MUST NOT be constructible without an actor.

A store without an actor can read across actors, and it collects domain data that belongs to no actor. A rule that depends on every call site to set the scope fails at the first call site that forgets. When no unscoped DataLayer can be constructed, a missed scope cannot break DL-07-001.
Extends: DL-07-001
DL-07-018 MUST NOT This codebase MUST NOT provide a shared, unscoped or "admin" DataLayer.

A shared or admin store is a global view across actors, which CM-01-001 forbids. If one exists, any caller can reach it and read past the isolation that DL-07-001 gives.
Extends: DL-07-002
DL-07-019 MUST NOT A DataLayer factory MUST NOT return an instance whose actor is unset.

Most code gets its store from a factory, not from a constructor. A factory that could return an unscoped instance would reopen the gap DL-07-002 closes.
Extends: DL-07-002
DL-07-003 MUST This codebase MUST derive each actor's store from the configured db_url, which it treats as a template, not as a location.

A single configured location cannot express one store per actor.
Implements: DL-07-001
DL-07-020 MUST NOT This codebase MUST NOT pass an already-derived store URL back through the derivation.

Derivation is not idempotent and cannot be made so, because a suffix cannot be stripped unambiguously — app7-vendor is indistinguishable from app7 plus vendor — so re-deriving silently produces a third store.
Extends: DL-07-003
DL-07-004 MUST An in-memory store MUST be named such that its identity is carried entirely by its URL, not by the identity of an engine object held in a cache.

If a Python engine object carries the identity of an in-memory store, two applications in one process that host the same actor can share one store by accident, because both URLs say :memory:. A named database makes the URL the only source of store identity, for file-backed and in-memory stores. Tests must respect two results of this rule. Two DataLayers built for the same actor id are the same database. Two scenarios that must not see each other's rows therefore need two actor ids.
Extends: DL-07-003
DL-07-005 MUST Code that reaches another actor's store MUST name that access at the call site.

Makes a fan-out explicit rather than something a forgotten filter grants.
Extends: DL-07-001
DL-07-021 MUST clone_for_actor MUST be the only route to another actor's store.

One named route makes every cross-actor read easy to find. CasePersistence declares clone_for_actor, so a cross-actor read is visible in the type as well as in the code.
Implements: DL-07-005
DL-07-022 MUST Code that needs a node-wide view MUST build it by enumerating the hosted actors and reading each one's store, not from a single query.

A single query over all stores is a cross-actor read that no call site names. A fan-out over the hosted actors names each store it reads.
Extends: DL-07-005
DL-07-006 MUST A URL path segment naming an actor MUST be resolved to a canonical actor URI by computation from the node's own base URL, without a registry lookup or a scan over stored actor records.

A scan is a cross-actor read, and it could return a peer's record — an actor this node does not host — because since DL-07-007 a hosted actor's store is full of peer records. Computation also means only an actor whose id already has this node's shape is addressable here, which is correct: an id under another authority names a process elsewhere.
Implements: ARCH-13-003
DL-07-007 MUST A peer actor's record MUST live in the address book of each hosted actor that knows it, not in a node-global store.

An actor's view of its peers is that actor's own data, per the Actor Knowledge Model: what an actor knows is bounded by what it has received. This is safe because delivery derives a recipient's inbox URL from its URI alone and never reads the peer's stored record.
Extends: DL-07-001
DL-07-023 MUST GET /actors/ MUST return only the actors the node hosts.

A peer is not something the node hosts. It is an address that some hosted actor happens to know, so listing it would claim an actor that lives elsewhere.
Extends: DL-07-007
DL-07-008 MUST Retry and dead-letter bookkeeping for an actor's outbox MUST live in that actor's own store.

Delivery bookkeeping about an actor's own outbox is that actor's own data, so it is subject to DL-07-001 like any other row.
Refines: DL-07-001
Extends: OX-13-001
DL-07-024 MUST NOT This codebase MUST NOT key an actor's outbox retry or dead-letter bookkeeping by an actor column in a shared table.

A key of (actor_id, activity_id) in a shared table brings back the filter-column layout that DL-07-001 replaces. A key of activity_id alone in the actor's store also makes an attempt counter single-valued, so one activity cannot collect two rival counts.
Extends: DL-07-008
DL-07-010 MUST POST /actors/ MUST reject with 422 an absolute actor_id whose authority (host and port) differs from the authority of the node's configured base URL.

If the node creates a store for each posted id, it claims to host actors that live elsewhere. Two foreign ids with the same final path segment then share one store, and the second actor gets the record of the first. A check of the authority at the route keeps the node from hosting a foreign actor. See ADR-0081.
DL-07-027 MUST NOT POST /actors/ MUST NOT create a store or an actor record for an actor_id that it rejects for a foreign authority (DL-07-010).

A rejected request that still opened a store would leave the node half-hosting the foreign actor. Later reads would find a store that the 422 said does not exist.
Extends: DL-07-010
DL-07-028 MUST This codebase MUST register a peer actor through POST /actors/{actor_id}/peers/. That route writes the peer's actor record into the store of the hosted actor the path names (DL-07-007).

A peer is registered in the store of the hosted actor that knows it, so hosting an actor and knowing an actor stay separate (ADR-0081).
Implements: DL-07-007
DL-07-029 MUST POST /actors/{actor_id}/peers/ MUST answer 404 when the path names no actor this node hosts.

A peer record needs a hosted actor's store to live in. Creating one for an unhosted actor would make the node host that actor by accident.
Extends: DL-07-028
DL-07-030 MUST POST /actors/{actor_id}/peers/ MUST be idempotent: registering a peer id the hosted actor already holds returns the existing record, not a second one.

A client may register the same peer again, for example on a retry. A second record for one peer would give later reads two answers for one actor.
Extends: DL-07-028
DL-07-011 MUST A node MUST enumerate the actors it hosts from the stores of its own storage deployment: the db_url template its app declares, or the configured db_url only when the app declares none. This holds in memory mode as in file mode.

File mode scopes enumeration by construction: it lists the files named after the node's template. Memory mode listed every store any app in the process had opened, so nodes sharing a process (the demo harness, the scenario recorder) opened empty stores for each other's actors and flooded runs with store-sharing warnings (#5319). In production one process is one node, so the configured db_url is the node's own deployment.
Extends: DL-07-022
DL-07-012 MUST A node MUST map each enumerated store's slug back to an actor id through its own base URL: the one its app declares, or the configured one only when it declares none.

A slug names a store, not an actor (DL-07-004). Two in-process nodes that share a slug, such as each node's primary, are different actors, and only the node's own base URL says which one this node hosts.
Extends: DL-07-011
DL-07-013 MUST An in-memory node MUST NOT list as hosted an actor whose store was opened only under another deployment in the same process, or a scratch store.

The process-wide store cache holds every deployment's stores and the ~ scratch stores. Listing them made GET /actors/ and /info open an empty store on this node for each foreign actor (#5319).
Refines: DL-07-011
DL-07-014 MUST A node-wide operation over hosted actors, such as the admin reset, MUST open each actor's store under the same deployment it enumerated the actor from.

The reset fallback opened stores under the configured db_url, so on a node that declares its own template it cleared another deployment's stores, left its own untouched, and still reported success (#5319).
Extends: DL-07-011

Demo-Only DataLayer Inspection Routes

The routes under /actors/{actor_id}/datalayer/... read an actor's store directly. They exist so that demo scripts and the demo UI can check system state, and they belong to the demo-only API: a production deployment does not expose them. HTTP-09 and ARCH-20-006 say how a read renders what it serves; this group says what a read reaches.

ID Priority Requirement Related
DL-09-001 MUST A DataLayer inspection route MUST serve every row the store holds, under the key the store holds it by.

A demo check reads system state through these routes. A row that is stored but cannot be read by its key makes the check report a state the actor is not in, for example a key with one slash that the route split into a type and an id.
DL-09-002 MUST Every DataLayer inspection route that serves one row MUST answer the same body for it.

A list read and a by-key read of one row are two views of one stored fact. If they disagree, a demo check passes or fails on which route it happened to use, as when a list rebuilt each Offer as its base class and dropped the inline object's role.
DL-09-003 MUST NOT A DataLayer inspection route MUST NOT mint an id or read the clock.

A read reports what is stored. An id or time made at read time is a value no actor stated, so two reads of one row differ and a demo recording changes on every run.

Demo CI — GitHub Actions Demo Integration Workflow

Requirements for a GitHub Actions workflow that builds and runs Vultron demo containers on pull requests, and for hardening the demo runner to exit non-zero when the demo fails — closing the gap where tests pass while the demo produces silent failures. Includes requirements for the invariant harness to run as an independent CI gate so failures are visible even when the demo itself also fails.

File ID: DEMOCI

Demo Runner Failure Signalling

ID Priority Requirement Related
DEMOCI-01-001 MUST The demo runner MUST exit with a non-zero exit code when the demo scenario fails, regardless of whether the Python process itself raised an unhandled exception.

docker compose --exit-code-from demo-runner requires a non-zero exit to surface failures in CI; a process that logs errors but exits 0 is indistinguishable from a successful run at the CI level.
DEMOCI-01-002 MUST The demo runner MUST treat any HTTP 404 response from an actor endpoint as a demo failure.

A 404 from an actor inbox or trigger endpoint means the target route does not exist, which is a protocol error, not a transient condition.
DEMOCI-01-003 MUST The demo runner MUST accumulate all errors encountered during the scenario and raise a typed DemoFailureError at the end of the scenario run, rather than halting at the first error.

Accumulating errors produces a complete diagnostic picture of all failures in a single run; stopping at the first error obscures subsequent steps that may also be failing.
DEMOCI-01-004 MUST Error detection and accumulation MUST be implemented by the demo_step, demo_check, and demo_gate context managers in vultron/demo/utils/failures.py.

All demo steps and checks already run inside these context managers. When the error accumulation is in the same place, every step and every check records its failure the same way, and no scenario needs its own error-handling code. demo_gate records a failure in the same way as demo_check, and it also stops the steps that need the failed precondition (DEMOCI-01-007).
DEMOCI-01-005 MUST DemoFailureError MUST be a subclass of VultronError.

A typed error lets the runner and the tests tell a demo failure apart from any other error. As a VultronError, it is in the same error hierarchy as the other project errors (EH-01-002).
Refines: EH-01-002
DEMOCI-01-012 MUST This codebase MUST define DemoFailureError in vultron/errors.py.

One module holds the project's error classes (EH-01-003). When DemoFailureError is defined there, the runner and the tests import it from the same place as every other project error.
Extends: DEMOCI-01-005
DEMOCI-01-006 MUST Every scenario entry-point function MUST call reset_demo_failures() as its first action.

DEMOCI-01-003 and DEMOCI-01-004 specify how failures accumulate, but not where the accumulator starts. A scenario that does not reset it first can inherit the failure state of an earlier run.
Implements: DEMOCI-01-003
DEMOCI-01-013 MUST Every scenario entry-point function MUST call assert_demo_success() as its last action before it returns.

The call turns the accumulated failures into a DemoFailureError, so CI sees a failed run. With the reset of DEMOCI-01-006, it forms the bookends of the failure accumulator. A scenario that skips the call exits without reporting the failures it recorded.
Implements: DEMOCI-01-003
DEMOCI-01-007 MUST A causal precondition MUST be expressed with a demo_gate context manager, distinct from demo_check.

Accumulate-and-continue is correct for verification assertions — report every failed check, not just the first — and wrong for preconditions, where continuing buries the real failure under secondary ones and makes the gate indistinguishable from a comment. Both behaviours are needed, so they need distinct names. See ADR-0058 and EDF-06-005.
Implements: EDF-06-005
DEMOCI-01-008 MUST On failure, demo_gate MUST record the failure in the accumulator exactly as demo_check does.

Gate failures must be accumulated so the exit-code contract of DEMOCI-01-001 and DEMOCI-01-003 applies uniformly, regardless of whether the failed check is a precondition or an advisory assertion.
DEMOCI-01-009 MUST On failure, demo_gate MUST prevent execution of the steps that depend on the unmet precondition.

Continuing past a failed precondition buries the root cause under secondary failures from steps that assumed the precondition was met.
DEMOCI-01-010 MUST demo_check MUST remain advisory: it records a failure in the accumulator and continues execution.

Advisory accumulation is the correct behaviour for verification assertions — every failed check should be reported in a single run rather than stopping at the first one.
DEMOCI-01-011 MUST A scenario MUST run each poll or verification call that raises on timeout, such as wait_for_*, inside a demo_step, demo_check or demo_gate context. A call through a shared helper that opens the context itself also meets this rule.

DEMOCI-01-003 requires all errors of a run to be reported together. A wait that raises outside a demo context escapes the failure accumulator and stops the scenario at the first timeout. Then the other failures of the run are not reported, and the one that is can point at the wrong cause. A bare call looks correct in a review, so an architecture test checks every piece of scenario-level code.
Implements: DEMOCI-01-003 — Running a raising wait inside a demo context is how its timeout is accumulated instead of halting the scenario.
DEMOCI-01-014 MUST A shared helper that encapsulates a raising poll MUST open the demo_step, demo_check or demo_gate context itself.

Every caller of such a helper then inherits the wrap, and no caller can forget it. wait_for_participants_on_replicas and wait_for_replica_ledger_coverage are such helpers.
Extends: DEMOCI-01-011

GitHub Actions Demo Workflow

ID Priority Requirement Related
DEMOCI-02-001 MUST This codebase MUST hold a dedicated GitHub Actions workflow, .github/workflows/demo-integration.yml, that runs the demo integration tests.

One workflow of its own gives the demo integration tests one place to run and one result on each PR, apart from the linting and unit-test pipeline.
DEMOCI-02-019 MUST NOT The demo integration workflow MUST NOT be merged into python-app.yml.

A separate workflow keeps the Docker Compose build time out of the existing linting and unit-test pipeline, and lets the two workflows run at the same time on a PR.
Derives from: DEMOCI-02-001
DEMOCI-02-002 MUST The demo workflow MUST trigger on pull_request events targeting the main branch, on push events to the main branch (see DEMOCI-05), and on workflow_dispatch events.

The pull_request trigger validates the ephemeral merge commit before a PR lands. The push-to-main trigger validates the actual merged main HEAD after a PR lands, closing the "green PRs, red main" gap where two individually-green PRs interact to break main with no post-merge signal (see DEMOCI-05).
DEMOCI-02-003 MUST Both the pull_request and push triggers MUST include the same paths filter, covering: vultron/ (excluding vultron/metadata/ and vultron/bt/), docker/, integration_tests/, test/ci/, pyproject.toml, uv.lock, .github/workflows/demo-integration.yml, .github/actions/build-demo-images/, .github/scripts/retry.sh, and .github/demo-scenarios.json.

These files can change the behavior of the demo containers, or the invariant checks that examine them. The filter skips the workflow when a change is only to docs or specs. The push filter and the pull_request filter must be the same, so that main checks every change that the pull request checked. vultron/metadata/** contains only tooling, which the actor services and the demo runner never import. vultron/bt/** is the legacy simulator. Only the vultrabot group in vultron/demo/cli/vultrabot_commands.py imports it (test/architecture/test_demo_no_bt_imports.py), and no CI scenario runs that group. The workflow file, the shared build action and the retry helper that the invariant job sources are in the filter, so a change to any of them runs the workflow. The CI matrix comes from .github/demo-scenarios.json (DEMOCI-06-004). Scenario code is already under vultron/**. The file is generated from the scenario registry (DEMOCI-11-004, DEMOCI-11-005), so a change to which scenarios run also changes the file, and the filter on it runs the workflow.
DEMOCI-02-004 MUST The demo workflow job MUST be skipped for Dependabot pull requests, detected via the condition if: "!startsWith(github.head_ref, 'dependabot/')".

Dependabot PRs arrive in waves (e.g., weekly dependency bumps) and are unlikely to break the demo; running the full container stack on each one wastes CI resources. The python-app.yml test suite still guards against broken dependencies on Dependabot PRs — which holds only because its path filter includes uv.lock (DEMOCI-02-016).
DEMOCI-02-005 MUST The demo workflow MUST build the Docker images using docker/docker-compose-multi-actor.yml and run the rv demo scenario (DEMO=rv) as the initial CI scenario.

The multi-actor compose file starts the actor containers that the demos need. The rv scenario is the simplest scenario with two actors, so it gives a baseline that other scenarios add to (DEMOCI-03-001).
DEMOCI-02-006 MUST Demo failure MUST be detected via the exit code of the demo-runner container, using the docker compose flag --abort-on-container-exit --exit-code-from demo-runner.

The exit status of the demo-runner container is the result of the demo (DEMOCI-01-001). Without these flags, docker compose keeps the other containers running after the demo ends, and its own exit status does not show if the demo failed.
DEMOCI-02-007 SHOULD The workflow SHOULD use Docker layer caching to avoid rebuilding unchanged dependency layers on every run.

A demo job builds several images. Layer caching can make the build shorter when only the source code changed. GitHub gives the cache tokens (ACTIONS_RUNTIME_TOKEN, ACTIONS_CACHE_URL) only to uses: steps, not to run: steps in a composite action. Thus a cache export must run in a uses: step.
DEMOCI-02-008 MUST The workflow MUST upload all container logs as a CI artifact when the demo job fails or is cancelled.

Container logs are diagnostic data, so they are necessary only when a job does not pass. A job can be cancelled when a container stops responding and the job reaches its timeout. If the workflow does not collect the logs on that path, nobody can find the cause of the hang.
DEMOCI-02-020 MUST NOT The workflow MUST NOT upload container logs when the demo job succeeds.

When the job passes, the logs only add artifacts that nobody reads.
Extends: DEMOCI-02-008
DEMOCI-02-009 MUST The demo workflow job MUST have a timeout of 15 minutes (timeout-minutes: 15).

The rv demo currently takes 3–5 minutes; a 15-minute cap prevents an indefinite CI hang if a container gets stuck, while providing sufficient headroom for slow runners.
DEMOCI-02-010 MUST The workflow MUST include a teardown step that runs docker compose down -v after the demo job (success or failure) to release Docker volumes and stop all containers.

GitHub Actions self-hosted runners and persistent environments accumulate stale Docker state if teardown is skipped.
DEMOCI-02-011 MUST The demo-integration.yml workflow MUST define a concurrency group keyed on ${{ github.workflow }}-${{ github.ref }}.

When commits land quickly during iterative work, queued demo runs pile up and waste CI minutes while delaying feedback. A single concurrency group keyed on workflow + ref collapses bursts on any branch to the newest run. On main a 60-second debounce step (DEMOCI-02-014) throttles burst merges without requiring per-commit granularity — a time-range bisect across a typical 4–6 PR batch is sufficient to identify regressions.
DEMOCI-02-013 MUST The concurrency group MUST set cancel-in-progress: true on all triggers so that a newer push always cancels superseded in-progress and queued runs.

Cancelling superseded runs reclaims CI minutes and reduces feedback latency on both PR branches and main. Burst-merge throttling on main is handled by the debounce action (DEMOCI-02-014) rather than by suppressing cancellation.
DEMOCI-02-014 MUST The .github/actions/debounce-main-push composite action MUST be invoked immediately after actions/checkout in each job that performs expensive work (the scenarios job in demo-integration.yml, and each stage-1 job in python-app.yml). The action sleeps 60 seconds only when github.event_name == 'push' and github.ref == 'refs/heads/main'; PR and workflow_dispatch runs are unaffected.

With cancel-in-progress: true on all triggers, a burst of merges to main would each spin up a full runner fleet and immediately cancel the previous one, leaving only the last at full cost. The sleep ensures that rapid successive pushes cancel each other before any real work starts, so only the last commit in a burst actually pays the full suite cost. The guard on github.ref prevents the sleep from ever firing on PR or dispatch runs.
DEMOCI-02-015 MUST The cancel-in-progress field MUST be the boolean literal true (not an expression). Per-trigger differentiation is handled by the debounce action (DEMOCI-02-014), not by the concurrency block.

Using a literal avoids the maintenance burden and reader confusion of an inline expression. The debounce step is the single place that encodes push-to-main throttling logic.
See also: DEMOCI-02-014 — context for the reader
DEMOCI-02-012 MUST The docker compose down teardown step MUST specify a per-container stop grace period of no more than 30 seconds (e.g. --timeout 30). Docker's default 10-second SIGTERM window followed by unbounded SIGKILL retries is not sufficient when a vendor container wedges; without an explicit cap, compose down can consume the remaining CI job budget.

A container that stops responding can ignore SIGTERM. Without a stop limit, compose down can use the remaining time of the CI job. A 30-second limit for each container puts a bound on the teardown time. It also gives a container that operates correctly time to write its state before SIGKILL.
Extends: DEMOCI-02-010
DEMOCI-02-016 MUST Both the push and pull_request triggers of .github/workflows/python-app.yml MUST include uv.lock in their paths filter.

DEMOCI-02-004 skips the demo workflow on Dependabot pull requests because python-app.yml still tests them. A Dependabot update inside an existing version range changes only uv.lock. If uv.lock is not in the path filter, that update can merge with no test run at all.
DEMOCI-02-021 MUST Both the push and pull_request triggers of .github/workflows/python-app.yml MUST include docs/reference/examples/** in their paths filter.

The committed vocab examples under docs/reference/examples/ are an input to test/architecture/test_vocab_examples_current.py, which compares each one byte for byte with a fresh generation. They are the only such input that lives outside vultron/ and test/, so without this entry a pull request that hand-edits or half-regenerates an example and nothing else matches no path filter and runs no test at all — the same failure mode DEMOCI-02-016 exists to prevent for uv.lock (#4506, #5776).
Extends: DEMOCI-02-016

Extensibility for Additional Demo Scenarios

ID Priority Requirement Related
DEMOCI-03-001 SHOULD The demo workflow SHOULD be extended to include additional demo scenarios (e.g., three-actor, multi-vendor) as each scenario reaches a stable, reproducible state.

Starting with the rv scenario lets CI run reliably while more complex scenarios are still being developed. Additional scenarios add coverage without blocking CI on unstable demos.
DEMOCI-03-002 MUST When a new demo scenario is added to the codebase, it MUST be registered in the scenario registry in the same PR. The generated .github/demo-scenarios.json then includes it in the demo-integration.yml matrix (DEMOCI-11-001, DEMOCI-11-004).

A scenario that CI does not run can stop working, and nobody sees it until a person runs the demo. The CI matrix is generated from the registry, so registration in the same pull request as the scenario gives the scenario a matrix entry when it merges.
Refines: DEMOCI-11-001
See also: DEMOCI-11-004 — context for the reader
DEMOCI-03-003 SHOULD Each demo scenario added to CI SHOULD be run as a separate job (or matrix entry) so that failures are independently reported and one scenario failure does not prevent other scenarios from running.

When all scenarios run in one job, the first failure can stop the other scenarios, and the result does not show which scenario failed. A separate job or matrix entry for each scenario gives each scenario its own result. One failure then does not hide the results of the other scenarios.
DEMOCI-03-004 MUST Each registered scenario MUST run as its own entry of the demo job matrix in demo-integration.yml, with no edit to the workflow for that scenario.

Parallel matrix entries keep the wall-clock time of CI bounded as scenarios are added, and give each scenario its own result. The scenarios job builds the matrix from the generated .github/demo-scenarios.json (DEMOCI-11-004). Registration with @scenario in the same PR (DEMOCI-03-002) is thus the only step that a new scenario needs (ADR-0098).
Refines: DEMOCI-03-003
DEMOCI-03-006 MUST The demo job of demo-integration.yml MUST run each matrix entry with --abort-on-container-exit --exit-code-from demo-runner (DEMOCI-02-006), timeout-minutes: 15 (DEMOCI-02-009), and the log-upload and teardown steps of DEMOCI-02-008 and DEMOCI-02-010.

One job definition serves every matrix entry, so each scenario gets the same failure signal, time limit and cleanup as rv. A scenario whose job differed could hang past the time limit, or leave its containers running for the next job.
Extends: DEMOCI-03-004
Refines: DEMOCI-02-006
Refines: DEMOCI-02-008
Refines: DEMOCI-02-009
Refines: DEMOCI-02-010
DEMOCI-03-005 MUST Each matrix entry of the demo CI workflow MUST declare a test_file field that names the invariant test file of its scenario, such as test/ci/invariants/test_rv_invariants.py.

An explicit file path makes the link from a scenario to its invariant tests declarative and visible in each generated .github/demo-scenarios.json entry (DEMOCI-11-004), whose test_file is derived from the registered scenario name (DEMOCI-11-003).
Extends: DEMOCI-03-004
DEMOCI-03-007 MUST The case-ledger invariant step MUST run pytest on the test_file path of its matrix entry, not on the -m case_ledger_invariants marker alone.

The marker alone relies on each test file skipping when its devlogs directory is absent. That is an implicit, fragile coupling between the state of the filesystem and the selection of tests. The explicit path runs exactly the tests of the scenario that ran.
Depends on: DEMOCI-03-005

Invariant Harness as an Independent CI Gate

ID Priority Requirement Related
DEMOCI-04-001 MUST The case-ledger invariant harness for each demo scenario MUST run as a separate CI job (distinct from the demo-runner job), so that invariant failures produce an independent pass/fail status on the pull request that is visible even when the demo job also fails.

When the demo run and the invariant checks are in the same job, a demo failure is the first thing a reviewer sees, and an invariant failure in the same output is easy to miss. A missing protocol phase can then stay hidden through many fix cycles. A separate job gives the invariant checks their own status, which a reviewer sees when the demo job also fails.
DEMOCI-04-002 MUST The invariant-harness job MUST declare a needs: dependency on the demo job of the same scenario matrix entry.

The separate invariant job exists to give a result when the demo fails. needs: on the demo job makes it start only after the demo uploads its artifacts.
Extends: DEMOCI-04-001
DEMOCI-04-010 MUST The invariant-harness job MUST use if: always(), so that it runs whether the demo job passed or failed.

Without if: always(), a failed demo job skips the invariant job, and the run that most needs an invariant result gets none.
Extends: DEMOCI-04-002
DEMOCI-04-011 MUST The workflow MUST skip the invariant-harness job when the demo job is cancelled (DEMOCI-04-007).

A cancelled demo job is a third outcome, apart from pass and fail, and it uploads no artifact. An invariant job that ran after a cancellation would fail only at download-artifact, and report a failure that is not about the invariants.
Extends: DEMOCI-04-002
DEMOCI-04-003 MUST The invariant-harness job MUST download the scenario's case-log JSONL artifact produced by the demo job before running pytest, so that the harness reads the actual output of the demo run that completed in that workflow execution.

The invariant job runs on a different runner from the demo job. The artifact is the only path from the output of the demo to the invariant checks. When the job uses the artifact from the same workflow run, the checks examine the demo output of that run, not an older or a local output.
Extends: DEMOCI-04-001
DEMOCI-04-004 MUST Each scenario's invariant test file, such as test/ci/invariants/test_rv_invariants.py, MUST include an expected-semantic-types list that covers every protocol phase the scenario is designed to exercise. The list is not limited to the universal phases (DEMOMA-16-001) that all scenarios share.

A shared minimal list (validate_report, add_participant_status_to_participant, close_case, add_note_to_case, engage_case) does not guard against a scenario-specific phase (e.g. notes-exchange) regressing silently. Each scenario's expected-semantic-types list must reflect what that scenario is designed to prove end-to-end.
Uses definition from: DEMOMA-16-001
DEMOCI-04-005 MUST The invariant-harness job MUST NOT run for Dependabot PRs, matching the demo job's exclusion (DEMOCI-02-004).

A Dependabot pull request skips the demo job (DEMOCI-02-004), so no case-log artifact exists. If the invariant job runs, actions/download-artifact fails, and each Dependabot pull request shows a failed check that has no relation to its change. The requirement is this result, not a specific expression. The scenarios job applies the exclusion one time (DEMOCI-02-004), and the invariant job inherits it through needs.scenarios.result. When the check is in one place, no copy of it can become different. always() alone is not sufficient, because it runs the job when an upstream job was skipped (DEMOCI-04-006).
Constrains: DEMOCI-04-010
Uses definition from: DEMOCI-02-004
DEMOCI-04-006 MUST The Dependabot exclusion guard for the invariant-harness job MUST be enforced such that a bare always() condition cannot resurrect the job when an upstream job was skipped.

always() alone runs the job even when an upstream job was skipped, which is exactly the spurious-failure case when Dependabot PRs skip the demo job but trigger the invariant-harness job.
DEMOCI-04-007 MUST Because the Dependabot exclusion is applied once on the upstream scenarios job (DEMOCI-02-004, DEMOCI-06-008), the invariant-harness if: MUST pair always() with a check that the scenarios job succeeded AND a check that the demo job was not cancelled, i.e. always() && needs.scenarios.result == 'success' && needs.demo.result != 'cancelled'.

always() with the check on the scenarios result lets the invariant job run after a demo failure, but not when the scenarios job was skipped. The check on the demo result is for a different case. The concurrency group (DEMOCI-02-013) can cancel a push-to-main run before the demo job uploads its case-log artifact. Then download-artifact (DEMOCI-04-003) fails with "Artifact not found", and the cancellation becomes a job failure. The notify job (CISEC-05-001) then files a ci:main-failure issue for a failure that did not occur. When the invariant job is skipped after a cancellation, the run has no failure result, and notify leaves the result to the newer run. The pass path and the true failure path (DEMOCI-04-010) do not change. Sometimes one demo matrix job fails and a newer push then cancels the other matrix jobs. GitHub does not document whether the combined needs.demo.result is then failure or cancelled. If it is failure, the invariant job runs and notify files an issue, which is correct, because a real failure occurred.
Implements: DEMOCI-04-011
Refines: CISEC-05-016
See also: DEMOCI-02-004 — a "because" rationale
See also: DEMOCI-06-008 — a "because" rationale

Post-Merge Validation on the Default Branch

ID Priority Requirement Related
DEMOCI-05-001 MUST The demo workflow MUST run the full demo + invariant-harness matrix against the main branch HEAD on push events to main (path-filtered per DEMOCI-02-003), producing a commit status on the merged result.

The pull_request trigger checks only the temporary merge commit of the pull request with main at that time. It does not check the result when other pull requests merge at about the same time. Two pull requests that each pass alone can together break main. The path filter runs the pull_request trigger only when a later pull request changes a filtered path, so a broken main can stay untested until then. A push-to-main run checks the demos and the invariants on main itself after each burst of merges (DEMOCI-05-002).
Refines: DEMOCI-02-002
Uses definition from: DEMOCI-02-003
DEMOCI-05-002 MUST Main-branch demo runs MUST produce a pass/fail signal for each burst of merges. A burst is defined as a sequence of merges separated by less than the debounce window (60 seconds, per DEMOCI-02-014); only the last commit in a burst runs to completion. Per-commit granularity on main is not required: a time-range bisect across a typical 4–6 PR batch is sufficient to identify regressions.

A full demo run on each merge uses many runners, and in a burst of merges most of those runs are cancelled by the next merge. One result for each burst gives main a pass or fail signal at a lower cost. A burst is a small number of pull requests, so a search across the commits of one burst can still find the commit that caused a regression.
Supersedes: DEMOCI-05-001
Uses definition from: DEMOCI-02-014
DEMOCI-05-004 MUST The push-to-main trigger MUST carry the same Dependabot exclusion semantics as the pull_request trigger, where they apply.

Push events to main do not come from dependabot/ head refs, so the guard need not be repeated on the push path. The trigger still must not run a Dependabot change that the PR path would refuse.
Extends: DEMOCI-05-001
DEMOCI-05-005 MUST NOT The workflow MUST NOT gate the on-main run behind a github.head_ref condition that would skip that run entirely.

github.head_ref is empty on a push event. The Dependabot guard of DEMOCI-02-004 passes on an empty string, but a different condition on github.head_ref can skip the on-main run with no error. Then main has no demo result at all.
Constrains: DEMOCI-05-004

Demo Scenario Coverage Model — PR Validation Set vs. Full Post-Merge Set

ID Priority Requirement Related
DEMOCI-06-001 MUST A scenario coverage analysis MUST be performed that maps each of the demo scenarios to the distinct Vultron protocol phases and message-type milestones it exercises, producing a coverage matrix.

The scenarios share common helper phases but each exercises a distinct set of protocol phases (e.g. invite_actor_to_case, offer_case_participant, accept_invite_actor_to_case). Milestone sets were often copied from simpler scenarios and may under-report what a scenario actually exercises. A complete per-scenario coverage matrix is prerequisite to designing a minimum PR validation set.
DEMOCI-06-005 MUST The scenario coverage analysis MUST inspect the milestone sets that each scenario script defines, and not assume that they are complete.

Milestone sets were often copied from simpler scenarios and may under-report what a scenario exercises. Only the scripts show what each scenario covers, so the coverage matrix is accurate only when it is built from them.
DEMOCI-06-011 MAY The scenario coverage analysis MAY update a scenario's milestone set where a copy from a simpler scenario has left it incomplete.

An analysis that finds an incomplete set can fix it in place. Then the coverage matrix and the scenario agree, and the gap does not stay open for a later pass.
DEMOCI-06-006 MUST The validated coverage matrix MUST be recorded in notes/demo-ci-scenario-coverage.md.

A notes file puts the coverage analysis where scenario authors read it. The matrix in the note is a checked copy, not the authority. DEMOCI-06-002 states the minimum PR validation set, and the registry declares the scenario set (DEMOCI-11-001).
DEMOCI-06-002 MUST The minimum PR validation scenario set is rv, rvcv-handoff, rcvcv, rcv-reject, rcv-embargo, and rcvv-embargo. Together these scenarios cover all distinct protocol semantic types exercised by the full scenario suite: the universal types (DEMOMA-16-001) plus invite_actor_to_case, offer_case_participant, accept_invite_actor_to_case, accept_actor_recommendation, accept_case_ownership_transfer, reject_invite_actor_to_case, invite_to_embargo_on_case, accept_invite_to_embargo_on_case, activate_embargo_on_case, and remove_embargo_event_from_case. The demo-integration.yml workflow MUST use this scenario set as the pull_request matrix and run only these scenarios on every PR commit.

The invariant jobs start only when every demo job in the set has finished (ADR-0052), so each extra scenario can make the wait longer. The minimum set keeps every protocol semantic type of the full suite covered, at a lower cost for each pull request. rv covers the baseline with two actors. rvcv-handoff adds invite, accept and ownership transfer. rcvcv adds offer_case_participant, accept_actor_recommendation and invite and accept chains with three or more actors. rcv-reject adds reject_invite_actor_to_case, the only scenario where a Vendor rejects an invitation after it enters RM.RECEIVED. rcv-embargo and rcvv-embargo are the only sources of the embargo semantic types, by different paths. The coverage matrix is in notes/demo-ci-scenario-coverage.md. See ADR-0052.
Derives from: DEMOCI-06-001
Uses definition from: DEMOMA-16-001
DEMOCI-06-003 MUST The demo-integration.yml workflow MUST run the full scenario suite on a push: branches: ["main"] trigger, whatever subset runs for PR validation. The full suite is rv, rvv, rvcv-extension, rvcv-handoff, rccv-extension, rccv-handoff, rcvcv, rcv, rcv-reject, rcv-embargo, rcvv-embargo and rv-csaf.

The post-merge run is the safety net for cross-PR regressions. It covers all scenarios, so every scenario variant keeps giving a case-log invariant signal on the default branch, after its phases leave the PR validation set.
Refines: DEMOCI-05-001
DEMOCI-06-004 MUST Per-event scenario selection (DEMOCI-06-002, DEMOCI-06-003) MUST be implemented by resolving the matrix before matrix expansion, not by a job-level if: condition that references the matrix context.

GitHub evaluates a job-level if: before it expands the matrix, so the matrix context does not exist at that point. A file that refers to it is valid YAML, and yaml.safe_load accepts it. But GitHub refuses the whole workflow at startup: no jobs start, there are no logs, no annotations and no job status, and the run shows the file path in place of the workflow name. Almost nothing shows this failure. It can stop the workflow on every branch, main included, for many runs before somebody sees it. GitHub reports the startup failure before it applies the branch filter. Thus the failure also shows on branches that the workflow does not run on, where a reader can ignore it. When both matrices come from one JSON file, the demo and invariant-harness jobs also have no copies of the matrix that can become different. actionlint finds the illegal context reference in CI and in pre-commit (DEMOCI-08-001).
Implements: DEMOCI-06-002
Implements: DEMOCI-06-003
DEMOCI-06-007 MUST CI MUST resolve the scenario list from a single declarative file (.github/demo-scenarios.json), with each entry carrying a boolean full_suite_only field.

When both matrices come from one file, the PR list and the post-merge list cannot become different, and full_suite_only is the one control for the selection by event. The file is generated from the scenario registry (DEMOCI-11-004), and the demo modules decide which scenarios exist (DEMOCI-11-001). This requirement is only about the file that CI reads the matrix from. That file must stay committed, because the scenarios job has no Python.
DEMOCI-06-008 MUST A scenarios job MUST filter the scenario list in .github/demo-scenarios.json according to github.event_name and expose the result as a JSON job output.

Centralising event-based filtering in a dedicated job ensures both downstream jobs consume the same filtered list and removes per-job if: conditions that would reference the matrix context.
DEMOCI-06-009 MUST The demo and invariant-harness jobs MUST derive their matrices via fromJSON() of the scenarios job output.

Using fromJSON of a shared upstream output guarantees both jobs expand the same scenario set and eliminates verbatim matrix duplication that could silently drift.
DEMOCI-06-010 MUST A job-level if: condition referencing matrix.* MUST NOT be used to gate matrix entries.

GitHub evaluates job-level if: conditions before expanding the matrix, so the matrix context is undefined at that point; referencing it causes a startup failure with no logs or per-job statuses.

Embargo Lifecycle Scenario CI Registration (rcv-embargo, rcvv-embargo)

ID Priority Requirement Related
DEMOCI-07-001 MUST The rcv-embargo scenario MUST be registered with in_pr_set=True (DEMOCI-11-001), so that its generated entry in .github/demo-scenarios.json (DEMOCI-11-004) carries "full_suite_only": false. The scenario runs on the first Reporter, Coordinator and Vendor slots of the fixed cast (DEMOCI-11-021) and the case-actor service.

The embargo semantic types come only from the embargo scenarios (DEMOCI-06-002). In the PR set, rcv-embargo checks the embargo lifecycle on each pull request. The registry is the authority, and the JSON file is its generated copy.
Refines: DEMOMA-20-005
Refines: DEMOCI-11-001
Uses definition from: DEMOCI-11-021
See also: DEMOCI-11-004 — context for the reader
DEMOCI-07-004 MUST The test_file matrix entry for the rcv-embargo CI job MUST point to test/ci/invariants/test_rcv_embargo_invariants.py.

An explicit file path makes the scenario-to-test relationship declarative per DEMOCI-03-005. The path is derived from the registered name by convention (DEMOCI-11-003) and written into the generated .github/demo-scenarios.json entry (DEMOCI-11-004).
DEMOCI-07-005 MUST The devlogs directory for the rcv-embargo CI run MUST use scenario-role names: reporter, coordinator, vendor, case-actor.

Scenario-role names in devlogs match scenario code and make log archaeology easier and consistent with the post-DEMOMA-12 naming convention.
DEMOCI-07-002 MUST The rcvv-embargo scenario MUST be registered with in_pr_set=True (DEMOCI-11-001), so that its generated entry in .github/demo-scenarios.json (DEMOCI-11-004) carries "full_suite_only": false. The scenario runs on the first Reporter, Coordinator and Vendor slots of the fixed cast (DEMOCI-11-021), one character-actor slot for Vendor2, and the case-actor service.

The rcvv-embargo scenario needs a fourth actor beyond the three used by rcv-embargo; Vendor2 takes a character-actor slot of the multi-actor compose file, which CI starts as a whole. Devlog directories keep the scenario's own names (vendor2, not the slot name), so they name the part an actor plays here and make log archaeology easier.
Refines: DEMOMA-21-006
Refines: DEMOCI-11-001
Uses definition from: DEMOCI-11-021
See also: DEMOCI-11-004 — context for the reader
DEMOCI-07-006 MUST The test_file matrix entry for the rcvv-embargo CI job MUST point to test/ci/invariants/test_rcvv_embargo_invariants.py.

An explicit file path makes the scenario-to-test relationship declarative per DEMOCI-03-005. The path is derived from the registered name by convention (DEMOCI-11-003) and written into the generated .github/demo-scenarios.json entry (DEMOCI-11-004).
DEMOCI-07-007 MUST The devlogs directory for the rcvv-embargo CI run MUST use scenario-role names: reporter, coordinator, vendor, vendor2, case-actor.

Scenario-role names in devlogs match scenario code and make log archaeology easier and consistent with the RCVCV pattern (DEMOMA-19-007).
DEMOCI-07-003 SHOULD A follow-up coverage analysis SHOULD be performed after rcv-embargo and rcvv-embargo are implemented and passing in CI, to evaluate whether the minimum PR set defined in DEMOCI-06-002 requires expansion to preserve full embargo lifecycle protocol coverage.

The embargo semantic types (invite_to_embargo_on_case, accept_invite_to_embargo_on_case, activate_embargo_on_case, remove_embargo_event_from_case) are produced only by rcv-embargo and rcvv-embargo, so the minimum PR set preserves embargo coverage only while at least one of them is a member. The coverage matrix in notes/demo-ci-scenario-coverage.md is where that membership is checked against the harness semantic-type constants.
Extends: DEMOCI-06-001
Uses definition from: DEMOCI-06-002
DEMOCI-07-008 SHOULD When the follow-up coverage analysis is performed, it SHOULD update notes/demo-ci-scenario-coverage.md, DEMOCI-06-002, and DEMOCI-06-003 to reflect its conclusions.

The analysis findings must be propagated to all three documents so that the coverage matrix, minimum PR set, and full scenario suite list remain mutually consistent.
See also: DEMOCI-06-002 — context for the reader
See also: DEMOCI-06-003 — context for the reader
DEMOCI-07-009 SHOULD If the embargo scenarios introduce protocol semantic types not covered by rv, rvcv-handoff, or rcvcv, the minimum PR set defined in DEMOCI-06-002 MUST be expanded.

No scenario other than rcv-embargo and rcvv-embargo commits an embargo semantic type, so a minimum PR set without them leaves the embargo lifecycle unexercised on PRs.
Uses definition from: DEMOCI-06-002
DEMOCI-07-010 SHOULD DEMOCI-06-003 SHOULD be updated to include rcv-embargo and rcvv-embargo in the full scenario suite list when they are wired into CI.

DEMOCI-06-003 names the full scenario suite explicitly; once the embargo scenarios are wired in, the list must be updated so the post-merge validation run is complete.
See also: DEMOCI-06-003 — context for the reader

Workflow Static Analysis (actionlint)

ID Priority Requirement Related
DEMOCI-08-001 MUST GitHub Actions workflow files MUST be statically analysed by actionlint in CI, via a dedicated workflow (.github/workflows/actions-lint.yml) whose path filter is scoped to .github/**.

A workflow can be syntactically valid YAML yet be rejected by GitHub at startup — the matrix-context-in-job-if: bug of DEMOCI-06-004 is the motivating case. Startup failures produce no logs, no annotations, and no job-level statuses, so nothing in the repository's own test or lint suite can detect them and the only symptom is a bare red X. actionlint resolves context availability per field and reports the illegal reference as a one-line error with the exact position. Pinning by version and checksum keeps CI reproducible and prevents a retagged or compromised upstream release from silently altering what executes in the pipeline.
DEMOCI-08-003 MUST The actionlint check MUST NOT be added to python-app.yml, whose path filter is scoped to vultron/** and test/** and therefore would not trigger on a workflow-only change.

A workflow-only change (touching only .github/**) would not match python-app.yml's path filter, so placing actionlint there would leave workflow changes unchecked.
DEMOCI-08-004 MUST actionlint MUST be registered as a pre-commit hook so that workflow errors are caught before push.

A pre-commit hook catches the illegal context reference before it reaches CI, closing the feedback loop that otherwise requires a push and a CI run to surface the error.
DEMOCI-08-005 MUST The actionlint version used in CI MUST be pinned.

Pinning by version keeps CI reproducible and prevents a retagged upstream release from silently altering what executes in the pipeline.
DEMOCI-08-006 MUST The CI download of actionlint MUST be verified against a pinned SHA256 checksum.

A checksum verification prevents a compromised upstream release from silently altering what executes in the pipeline.
DEMOCI-08-002 MUST The actions-lint.yml workflow MUST verify that .github/demo-scenarios.json is a non-empty array.

The matrix is data, not inline YAML, so an error in it causes no YAML error. An empty array gives the scenarios job no scenario to run, and that job then fails on every pull request and on every push to main, far from the change that caused it. This check finds an empty array in the change that caused it, before any demo runs.
Extends: DEMOCI-08-001
DEMOCI-08-007 MUST The actions-lint.yml workflow MUST verify that every entry in .github/demo-scenarios.json has a non-empty string demo field, a non-empty string test_file field, and a boolean (not string) full_suite_only field.

A missing test_file key expands into a job that runs pytest ""; a string "false" is truthy to jq and would drop a scenario from the PR set.
DEMOCI-08-008 MUST The actions-lint.yml workflow MUST verify that no demo name is duplicated in .github/demo-scenarios.json.

A duplicated demo name collides on the upload-artifact name and one scenario's logs overwrite the other's.
DEMOCI-08-009 MUST The actions-lint.yml workflow MUST verify that at least one entry in .github/demo-scenarios.json has full_suite_only: false.

An empty PR validation set would let pull_request runs report a vacuous success with zero scenarios executed — the same false-green class of failure that DEMOCI-06-004 exists to prevent.
DEMOCI-08-010 MUST The actions-lint.yml workflow MUST verify that every test_file path referenced in .github/demo-scenarios.json exists in the repository.

A non-existent test_file path should be caught at schema-validation time rather than 15 minutes into a demo run.

Integration Branch Support

ID Priority Requirement Related
DEMOCI-09-001 MUST The workflow_dispatch trigger in demo-integration.yml MUST declare an optional ref input of type: string with an empty default. Its description says that it accepts a branch, tag or SHA to check out before the full demo suite runs.

When related bug-fix PRs land on a shared integration branch (e.g. fix/demo-ci), the full demo suite must run against that branch without a dummy PR to main. A workflow_dispatch ref input starts that run with one click in the GitHub UI.
DEMOCI-09-003 MUST All three actions/checkout steps of the workflow, in the scenarios, demo and invariant-harness jobs, MUST pass ref: ${{ inputs.ref &#124;&#124; github.ref }} unconditionally.

When inputs.ref is set, the suite runs against that ref. When it is empty or absent, as on every event other than workflow_dispatch, the expression falls through to github.ref. A conditional if: inputs.ref != '' guard instead would break the normal checkout with no error.
Extends: DEMOCI-09-001
DEMOCI-09-002 MUST An integration branch such as fix/demo-ci is done when it has merged to main and all its child issues are closed. A maintainer MUST then remove its name from the pull_request and push trigger branches: arrays in demo-integration.yml.

Stale branch entries in trigger arrays are dead configuration: the branch no longer exists, so the entries neither fire nor document anything. They can confuse a future maintainer about which branches are real targets.
DEMOCI-09-004 MUST When a maintainer removes an integration branch's name from those trigger arrays, the maintainer MUST also remove each # remove when merged comment that names the branch.

A comment that names a branch the triggers no longer list is as stale as the entry itself. Removing both at once keeps the trigger configuration consistent with the life of the integration branch.
Extends: DEMOCI-09-002

Case-Ledger Artifact Availability on Failure

ID Priority Requirement Related
DEMOCI-10-001 MUST Every demo scenario MUST export its case ledgers from a code path that runs whether or not its phases succeed. The shared scenario harness does so on both its exception path and its success path (DEMOMA-23-001).

demo_check and demo_step record failures and do not raise. Thus an exception that leaves a scenario is a serious failure, and those runs need the ledgers most. A dump placed only after the last phase is skipped by such an exception, and the run uploads no ledger when it is most necessary.
DEMOCI-10-002 MUST The case-ledger dump MUST always write a dump-manifest.json under devlogs/<demo-name>/, even when it captured no ledgers at all.

The upload-artifact step and the download of the invariant-harness job both need the artifact to exist. An always-present manifest makes the download succeed, and turns "nothing was uploaded" into a machine-readable statement of which actors were missing and why. The invariant harness can then report a real result instead of a download error.
Extends: DEMOCI-10-001
DEMOCI-10-015 MUST The dump-manifest.json MUST record demoName, caseId, ledgerFileCount, targetCount, an optional top-level reason, and one actors[] entry per dump target. Each actors[] entry carries actorName, routeKey, captured, entryCount, ledgerFile and reason.

The per-actor reason tells a dump that timed out apart from a scenario that never started. A timed-out dump records the error in the actor's reason with captured: false, while a pre-run CI sentinel (DEMOCI-10-006) records an empty actors array.
Extends: DEMOCI-10-002
DEMOCI-10-016 MUST The dump-manifest.json MUST record an unreplicatedActors[] list, empty when there is none. It holds one {actorName, routeKey} entry for each actor that acted in the case but holds no ledger replica to dump.

An actor with no replica has no ledger file to name it. The list lets the invariant harness resolve the entries of that actor to a name (DEMOMA-22-005).
Extends: DEMOCI-10-002
DEMOCI-10-003 MUST test/ci/invariants/common.py::load_devlogs() MUST fail — not skip — when a dump-manifest.json is present under the scenario's devlogs directory but no *-case-ledger.jsonl file exists.

For a developer who did not run the demo, no data means nothing to check, and a skip is correct. In CI, no data means that the scenario stopped. The manifest shows which of the two cases applies. Without this rule, the harness can pass for a scenario that wrote no ledger.
Uses definition from: DEMOCI-10-002
DEMOCI-10-008 MUST test/ci/invariants/common.py::load_devlogs() MUST fail when a dump-manifest.json is present under the scenario's devlogs directory but is unparseable.

An unparseable manifest indicates data corruption during the CI run; failing loudly surfaces this as a real harness error rather than a silent skip.
DEMOCI-10-009 MUST test/ci/invariants/common.py::load_devlogs() MUST skip only when there is no evidence the demo ran: no devlogs/ directory, no scenario sub-directory, or neither ledger files nor a manifest.

Skipping is appropriate only when a developer has not run the demo locally; the manifest distinguishes that case from a CI run that produced no artifacts.
DEMOCI-10-004 MUST A failure inside the case-ledger dump MUST NOT replace the exception that ended the scenario.

The dump runs on the failure path, when the system already has a fault, so the dump can also fail. If the dump error replaces the first exception, the run keeps its artifacts but loses the cause of the failure. The cause is the information that the dump on the failure path is there to keep.
Extends: DEMOCI-10-001
DEMOCI-10-010 MUST When the case-ledger dump fails, it MUST record its own failure through the accumulator and the manifest.

Recording dump failures in the manifest makes them machine-readable and distinguishable from a scenario that never started.
DEMOCI-10-011 MUST When the case-ledger dump fails, the original scenario exception MUST propagate unchanged.

Propagating the original exception unchanged ensures the root-cause diagnosis is not replaced by a secondary dump failure.
DEMOCI-10-005 MUST The invariant-harness pytest session MUST exit non-zero when every collected test was skipped.

When devlogs or a scenario directory are missing, load_devlogs() calls pytest.skip() in a fixture, and every test in the file skips. By default, pytest then exits with zero, and CI shows the invariant job as passed although it checked no invariant.
DEMOCI-10-017 MUST A pytest_sessionfinish hook in test/ci/invariants/conftest.py MUST set session.exitstatus = 1 when at least one test was reported and every reported outcome was "skipped".

The hook turns the empty pass of DEMOCI-10-005 into a failure. It acts only when some test was reported, so a session with no test at all keeps the exit status that pytest gives it.
Implements: DEMOCI-10-005
DEMOCI-10-006 MUST The CI demo job MUST write a pre-run sentinel dump-manifest.json under devlogs/<demo-name>/ before it builds the demo images and launches the demo-runner container.

scenario_harness() only runs when the demo-runner container starts and the scenario module imports successfully. Docker startup failures, import errors, and health-check sys.exit(1) calls all exit before scenario_harness() is entered, leaving devlogs/<demo>/ empty. The upload-artifact step then publishes nothing, the download-artifact step fails with "Artifact not found", and the invariant-harness job reports a plumbing error instead of an invariant result. The sentinel step closes this gap: the artifact directory is non-empty regardless of how early the runner exits, so the download succeeds and load_devlogs() reports a real failure via the manifest-without-ledgers path (DEMOCI-10-003). Writing it before the image build covers a failed build too, so every attempt uploads its own artifact (DEMOCI-04-008).
Uses definition from: DEMOCI-10-002
DEMOCI-10-012 MUST The pre-run sentinel dump-manifest.json MUST conform to the DEMOCI-10-015 and DEMOCI-10-016 schema. It holds caseId: null, ledgerFileCount: 0, targetCount: 0 and a reason string saying that the demo-runner has not started.

The sentinel must be schema-conformant so the invariant-harness job can parse and interpret it via the manifest-without-ledgers path (DEMOCI-10-003).
Uses definition from: DEMOCI-10-015
Uses definition from: DEMOCI-10-016
DEMOCI-10-013 MUST When the demo-runner reaches scenario_harness(), the harness MUST overwrite the pre-run sentinel with the real dump manifest.

Overwriting the sentinel ensures that a successful run does not leave misleading pre-run metadata as the artifact for the invariant-harness job to read.
DEMOCI-10-007 MUST When a dump-manifest.json under the scenario's devlogs directory has a non-null caseId, test/ci/invariants/common.py::load_devlogs() MUST return only the ledger entries whose case_id matches it.

Local demo runs can leave JSONL files for different cases in the same devlogs/ directory. Without a filter on the case, load_devlogs() joins them, and test_invariant_1_local_hash_chain_consistent reports prevLogHash mismatches that are not real. DEMOCI-10-015 makes the manifest record caseId, so load_devlogs() can keep only the entries of this run.
Uses definition from: DEMOCI-10-015
DEMOCI-10-014 MUST When test/ci/invariants/common.py::load_devlogs() fails because a dump-manifest.json is present but no ledger files are, its failure message MUST name the layer that failed.

A demo that stopped early still fails the harness (DEMOCI-10-003). But a message that calls an upstream demo fault "a real invariant failure" sends the person who examines it to the ledger, when the run tested nothing about the ledger. The manifest already holds the information that tells the cases apart (DEMOCI-10-015, DEMOCI-10-012).
Extends: DEMOCI-10-003
DEMOCI-10-018 MUST For an upstream abort, the load_devlogs() message MUST say that the ledger invariants were not exercised and point at the demo-integration job for the cause. An upstream abort is a run whose every manifest records caseId: null and targetCount: 0 with a reason other than the harness's crashed-dump backstop reason.

Such a run aborted before a case existed, or wrote only the pre-run sentinel. The cause is in the demo job, so the message sends the reader there and not to the ledger.
Refines: DEMOCI-10-014
DEMOCI-10-019 MUST For a manifest with the crashed-dump reason, the load_devlogs() message MUST say that the dump raised and that it is unknown whether a case existed.

A dump that raised leaves no record of the case. The message states only what the manifest supports, and does not call the run an upstream abort or an invariant failure.
Refines: DEMOCI-10-014
DEMOCI-10-020 MAY Only when a manifest names a case MAY the load_devlogs() failure message call the outcome a ledger invariant failure.

A manifest that names a case shows that the case existed and the dump ran, so missing ledgers then are a fault of the ledger layer.
Constrains: DEMOCI-10-014

Demo Scenario Registry and Derived Artifacts

Requirements for the self-registering demo scenario registry introduced by ADR-0098. The scenario set was previously restated by hand in eight-plus places with nothing enforcing agreement, and had already drifted: a documented vc sub-command named a demo script that never existed. These requirements make the demo modules the sole declaration point and every scenario table a derived artifact.

ID Priority Requirement Related
DEMOCI-11-001 MUST Each demo scenario module or package under vultron/demo/scenario/ MUST declare itself to the scenario registry at import time.

Only the demo module can know that the demo exists. A declaration in the module itself cannot be left out when a new module is written, and a module that omits it shows as a scenario on disk that the registry lacks. A scenario that outgrows one file becomes a package, and the package is still the one place that knows the scenario exists.
DEMOCI-11-036 MUST The scenario registry MUST be the only place that declares the set of implemented demo scenarios.

Any separate list, such as a data file, an import list or a documentation table, can leave out a scenario or name one that does not exist, and nothing fails. When every list is generated from the registry, they cannot disagree.
Extends: DEMOCI-11-001
DEMOCI-11-037 MUST NOT This codebase MUST NOT register a scenario that is specified but not yet built. Its spec group and the planned-scenario register declare it instead (DEMOCI-11-010).

A specified scenario that is not built is a normal state. A list cannot show the difference between that state and an available scenario unless the registry holds only the built scenarios.
Extends: DEMOCI-11-001
Derives from: DEMOCI-11-010
DEMOCI-11-002 MUST Registry discovery MUST enumerate the scenario package with a pkgutil-style walk of vultron/demo/scenario/ that returns each *_demo module and each *_demo package.

Import-time registration observes only the modules that were imported. A walk of the package imports every module, so a new demo registers without any other edit. A scenario can be a package, and a walk that skipped packages would hide it.
Depends on: DEMOCI-11-001
DEMOCI-11-038 MUST NOT Registry discovery MUST NOT rely on a hand-maintained list of imports.

A hand-written import list brings back the silent omission that the registry exists to remove: the new demo is written, nobody adds it to the list, and every generated table looks complete and is wrong. The AS2 vocabulary registry has the same discovery hazard.
Extends: DEMOCI-11-002
DEMOCI-11-003 MUST The scenario registry MUST derive a scenario's demo script, invariant harness and narrative page paths from its registered name, and store none of them. The paths are vultron/demo/scenario/<name_>_demo.py or the package vultron/demo/scenario/<name_>_demo/, test/ci/invariants/test_<name_>_invariants.py and docs/topics/scenarios/<name>.md, where <name_> replaces hyphens with underscores.

A stored path can be wrong about itself; a derived path either resolves or fails a check. Every registered scenario satisfies all three conventions, so no exception list is required, and introducing an override field would re-open the drift channel for every scenario rather than one. A scenario longer than one module can hold (CS-18-001) becomes a package of the same name, so its demo path is the module or the package, whichever exists, and the name alone still finds it.
DEMOCI-11-004 MUST .github/demo-scenarios.json MUST be generated from the scenario registry.

A hand-kept matrix file can disagree with the registry, and a scenario then runs in CI under a wrong name or not at all. A generated file, gated by its check mode (DEMOCI-11-005), always matches the registry.
Extends: DEMOCI-06-007
DEMOCI-11-039 MUST This codebase MUST keep .github/demo-scenarios.json committed.

The scenarios job resolves the matrix with jq right after checkout, in a job with no Python environment. The matrix thus cannot be computed at run time, and the file cannot be build-time-only.
Extends: DEMOCI-11-004
DEMOCI-11-040 MUST Each entry of .github/demo-scenarios.json MUST carry only the keys that the CI matrix consumes: demo, test_file and full_suite_only.

The entries are splatted into matrix: include:, so every extra key becomes a matrix variable visible to every step of two jobs.
Extends: DEMOCI-11-004
DEMOCI-11-041 MUST Every entry of .github/demo-scenarios.json MUST set full_suite_only to an explicit boolean.

The selection filter is select(.full_suite_only == false), so an omitted field silently drops a PR-set scenario from the matrix instead of raising an error.
Extends: DEMOCI-11-004
DEMOCI-11-005 MUST Every committed artifact generated from the scenario registry MUST be gated by a check mode wired into pre-commit, which fails when the committed artifact does not match the registry.

A generated file that is committed but ungated is just a hand-edited file with extra steps. The repository already runs this arrangement for docs/adr/index.md via the adr-index-sync hook.
Constrains: DEMOCI-11-004
DEMOCI-11-006 MUST NOT Documentation outside the MkDocs tree MUST NOT use {% include-markdown %} to source a scenario table.

The include-markdown plugin expands only during a MkDocs build, and mkdocs.yml references neither notes/ nor test/ci/. An include directive in either renders as literal text to every reader on GitHub and to every agent that reads the raw file.
DEMOCI-11-042 MUST A scenario table in documentation outside the MkDocs tree MUST be generated into its file or checked in place against the registry (DEMOCI-11-007). A table is checked in place when it interleaves hand-written columns that the registry does not hold.

Build-time rendering is the stronger guarantee, because no table is committed and drift is impossible. But it is available only inside the MkDocs tree, so a table outside it is generated or checked instead.
Extends: DEMOCI-11-006
Uses definition from: DEMOCI-11-007
DEMOCI-11-007 MUST Hand-written prose that enumerates scenarios — including DEMOCI-06-002, DEMOCI-06-003, the per-scenario requirements of the DEMOMA-16 group, the hand-written columns of the notes/ scenario tables, and the mkdocs.yml nav — MUST be checked for agreement with the scenario registry rather than rewritten to defer to it.

A requirement that defers its content to code is a weak requirement, and the per-scenario DEMOMA-16 requirements exist so that each scenario has a citable spec ID. Generate what is derivable and check what is prose — the split vultron/metadata/adr/index_gen.py already makes when it generates the ADR index but only checks the nav, whose labels are hand-written. The per-scenario DEMOMA-16 requirements are not a contiguous ID range and MUST NOT be selected as one: DEMOMA-16-008 is the spec-to-test sync rule, DEMOMA-16-012 and DEMOMA-16-013 are RCVCV event-count requirements, and DEMOMA-16-014 and DEMOMA-16-015 are per-scenario requirements for scenarios that are specified but not yet built.
See also: DEMOCI-06-002 — context for the reader
See also: DEMOCI-06-003 — context for the reader
DEMOCI-11-008 MUST NOT A consumer of a scenario table MUST NOT restate the number of demo scenarios in prose. The table is the count.

A count in prose is a second copy of the table. Each new scenario then needs an edit in each place that states the count, and a missed edit makes the prose wrong. This is MS-16-001 applied to the scenario set.
DEMOCI-11-009 MUST docs/topics/scenarios/index.md MUST render its scenario table at build time from the registry. No scenario table may be committed in that page.

The page sits inside the MkDocs tree, so markdown-exec can call the dumper during the build. That is a stronger guarantee than generation plus a --check hook (DEMOCI-11-005): with no committed table there is nothing to go stale, so drift is not detected but impossible. The weaker arrangement is used elsewhere only because CI and raw-file readers cannot run a MkDocs build. Stating this as a requirement is what makes the zero-drift claim ADR-0098 records for this page true rather than aspirational.
DEMOCI-11-010 MUST Every demo scenario that has a spec group MUST appear in exactly one of two places. An implemented scenario is in the scenario registry, and a scenario that is specified but not yet built is in the planned-scenario register in notes/demo-future-ideas.md. Neither membership is inferred from the other.

Scenario authors specify a scenario before they build it. But a specified scenario can then show in a table of available demos, and nothing tells it apart from a built one. Thus the registry holds only built scenarios, the planned register holds the rest, and a check confirms that each is in exactly one. The check also runs from the prose side, so the scenarios of DEMOMA-16-014 and DEMOMA-16-015 are not ignored.
DEMOCI-11-043 MUST Each entry of the planned-scenario register MUST carry its tracking issue and its spec IDs.

A planned entry that names no issue cannot be followed to the work that builds it, and one that names no spec IDs cannot be checked against the spec groups that the partition reads.
Extends: DEMOCI-11-010
DEMOCI-11-011 MUST The demo CLI, vultron/demo/cli/, MUST generate its per-scenario sub-commands from the scenario registry.

The registry is the one place that declares the scenarios. The container URL options differ for each scenario, and each scenario module declares them in a ROLES list of ActorRole values. One command factory reads that list, as in the ActorSession model (DEMOMA-26), and a test checks that the roles agree with the main() signature of the scenario (ADR-0098).
Implements: DC-01-002
DEMOCI-11-044 MUST The demo CLI MUST hold exactly one sub-command per registered scenario, and no scenario sub-command that the registry lacks.

A CLI that can omit or add a scenario on its own is a second list. A registered scenario that it leaves out cannot be run from the CLI.
Extends: DEMOCI-11-011
DEMOCI-11-045 MUST NOT A scenario sub-command MUST NOT be hand-declared, such as with a @main.command block in cli.py.

A hand-declared sub-command is a second list that can drift from the registry. A factory-built command and a hand-declared one look the same to click at run time, so the check reads the source.
Extends: DEMOCI-11-011
DEMOCI-11-012 MUST NOT A scenario narrative page, docs/topics/scenarios/<name>.md, and the index docs/topics/scenarios/index.md MUST NOT declare a status or maturity frontmatter key.

A page cannot know if its scenario passes (MS-16-002). A status: stable key that nobody checks can show on a page when its scenario fails, while the demo-integration workflow gives the current answer (DEMOCI-06-003). The maturity key is refused too, because a page has no maturity tier (ADR-0106). Prose that claims a result is wrong for the same reason, but a review must find it.
Derives from: MS-16-002
DEMOCI-11-046 MUST Every markdown page under docs/topics/scenarios/ other than the index MUST be the narrative page of a registered scenario, as DEMOCI-11-003 derives it. The check fails a page whose stem names no registered scenario. A shared _-prefixed {% include-markdown %} fragment is not a page (DF-09-007), and the check skips it.

The demo-integration workflow runs every registered scenario (DEMOCI-06-003). A page for a scenario that is not registered thus describes a scenario that no CI run exercises.
Uses definition from: DEMOCI-11-003
See also: DF-09-007 — context for the reader
DEMOCI-11-013 MUST Each branch point MUST be defined exactly once, as one branch-point table entry with its deciding role, presenter prompt and two or more choices. The table is the one in the scenario package, and it holds every branch point of the scenario tree.

Live mode and offline mode must offer the same choices (ADR-0104). One table that holds each branch point once is the single source for both modes, so their prompts and choices cannot become different.
DEMOCI-11-047 MUST Each branch-point choice MUST carry a presenter label and exactly one trigger: the next trigger of the branch point's role on the path.

Live mode offers each choice as one trigger POST (ADR-0104). A presenter takes control of a role at a branch point, so the choice is what that role does next on the path.
Extends: DEMOCI-11-013
DEMOCI-11-073 MUST After a run has recorded a failure, a declared step whose actor lacks the branch point's role MUST stop the story through demo_gate, not raise.

The role is then missing because an earlier act failed: an Invite whose trigger failed seats no participant. Raising would report a transport failure as a declaration defect, so the reader would check the branch-point table instead of the delivery. The gate keeps the first failure as the reported cause (DEMOCI-01-003, EDF-06-005). On a run with no failure, a missing role is a mis-declared step, and DEMOCI-11-047's check raises.
Refines: DEMOCI-11-047
DEMOCI-11-048 MAY Steps by other roles MAY run between a branch-point decision and the trigger of its choice.

The scenario plays the other parties until the next branch point, so their steps can occur between a decision and its trigger.
DEMOCI-11-049 MUST NOT A branch-point choice MUST NOT be a non-trigger action, such as a wait, a skip or a fall-through.

A choice that is not a trigger has no live form. A decision not to act is thus written as the next trigger of the role on that path ("report the fix ready", not "invite nobody"), and a party that does nothing shows as what the other party does next.
Extends: DEMOCI-11-013
DEMOCI-11-050 MUST NOT The prompt and the choice labels MUST NOT be declared anywhere outside the branch-point table, including on @scenario and in ui/.

Labels held in one table cannot become different between the live and offline modes. A second copy on the decorator or in the UI could drift from the table.
Derives from: DEMOCI-11-013
DEMOCI-11-014 MUST Each registered scenario MUST declare its full path — the ordered sequence of (branch point, choice) pairs from the tree's root to its ending, each naming an entry of the branch-point table (DEMOCI-11-013) — as the choices of its assembled story (DEMOCI-11-019).

Sibling scenarios such as rv and rvv are not a prefix of each other, so a pointer to a parent scenario does not treat them the same. A full path treats siblings the same, and the tree is the merge of the paths. The story is where the path is declared because it is also what walks it, so there is one statement of it rather than two that can disagree.
Uses definition from: DEMOCI-11-013
DEMOCI-11-022 MAY A branch point MAY occur more than once on one scenario's path (DEMOCI-11-014).

A tree node is a path prefix, not a branch-point identity, because the same decision can occur again on one path (a report can be invalidated and later validated).
Uses definition from: DEMOCI-11-014
DEMOCI-11-023 MUST Discovery MUST fail when a path names an unknown branch point or choice, when two scenarios declare the same path, or when one scenario's path is a strict prefix of another's, so that every registered scenario is exactly one ending of the tree.

A path that is a prefix of another path would make one scenario both an interior node and an ending, and two scenarios on one path would be one ending with two names. Failing at discovery stops a malformed tree before the index, the recordings or the UI read it.
Extends: DEMOCI-11-014
Uses definition from: DEMOCI-11-013
DEMOCI-11-015 SHOULD A scenario's name SHOULD keep the letter grammar of the existing names. Its leading letters spell, in order, the roles that join the case. They are r Reporter, v Vendor, c Coordinator and d Deployer, with one new letter for each further role. An optional hyphenated suffix names the outcome. A Vendor that reports its own vul joins as a Vendor, so its name begins with v.

A name is the stem of the module, the invariant harness, the narrative page, the scenario_start marker and the CI matrix entry, so a new name changes all of them. The grammar is a naming convention that review keeps, not a registry check: some joins occur in scripted steps that no choice records. The Finder letter f is retired with the Finder role (ADR-0078).
DEMOCI-11-051 SHOULD NOT A scenario's name SHOULD NOT be generated from the choices of its path.

A name generated from choices changes for every scenario below a new branch point. Each change renames the module, the harness, the page and the CI matrix entry of that scenario.
Extends: DEMOCI-11-015
DEMOCI-11-016 MUST The scenario-tree index the demo UI reads MUST be generated from the branch-point table and registered paths, committed under ui/src/data/, and drift-checked per DEMOCI-11-005.

The UI holds no copy of a protocol fact that a person keeps by hand (ADR-0128, ADR-0104). A generated index cannot become different from the registry without the drift test failing.
Refines: DEMOCI-11-005
Depends on: DEMOCI-11-014
DEMOCI-11-052 MUST The scenario-tree index MUST carry the branch-point table, the tree as nested nodes from the root, and one entry per scenario. Each entry holds the scenario's label, path and recording files.

The UI draws the tree and offers its choices from the index alone, so the index carries every part that the UI shows.
Extends: DEMOCI-11-016
DEMOCI-11-053 MUST The scenario-tree index MUST key the recording files of each scenario by both actor and case.

Planned scenarios split, merge and consolidate cases, so the recording of one actor can cover several cases. A key on the actor alone does not fit those scenarios.
Extends: DEMOCI-11-016
DEMOCI-11-017 MUST A check MUST compare the recorded ledgers of every two registered scenarios, up to the branch point where their paths part. Each recording's step marks locate that branch point in it. No registered scenario and no pair of them is held out of the comparison.

The comparison is what holds a declared branch honest: it fails when two scenarios do not run the same thing up to the point their paths say they diverge. Scoping it to a declared subset of the tree makes the pairs nobody listed the ones nobody checks, so the obligation is over every pair. A pair that parts at the root shares no ledger entries, because the root branch point is decided before the case exists; those pairs carry nothing and the pairs that part later are what the check rests on.
Depends on: DEMOCI-11-014
DEMOCI-11-018 MUST The comparison of DEMOCI-11-017 MUST be byte for byte: the ledger entries before the branch point are the same bytes in both recordings, ids and timestamps included.

Every scenario is written as composition, so a shared stretch is one copy of the code on one fixed cast under one seed (DEMOCI-11-020, DEMOCI-11-025): both recordings draw the same ids and read the clock the same number of times, and byte identity holds by construction. It is also the only form that catches a shared stretch writing the same objects in a different order. What a shared stretch must satisfy is in notes/demo-scenario-tree.md § "Composition".
Refines: DEMOCI-11-017
Depends on: DEMOCI-11-020
Depends on: DEMOCI-11-025
DEMOCI-11-034 MUST The flattened story of every registered scenario MUST be committed as a generated plot manifest. An entry lists the story's items in order: each choice by branch point, choice and deciding cast member, and each fragment by qualified name.

A reorder inside a shared fragment moves every scenario of its family alike, so DEMOCI-11-018 still passes. The plot is read from the stories without running them, so it costs nothing at PR time. A deliberate reorder shows as a manifest diff; in a consolidation PR that diff is a sign the change may alter what a scenario passes or fails on, which DEMOMA-17-002 forbids. The manifest cannot see an edit inside a fragment's body; DEMOCI-11-055's base-versus-head comparison can.
DEMOCI-11-035 MUST The drift check of DEMOCI-11-005 MUST fail when the committed plot manifest differs from the stories in the code.

A manifest nobody compares with the code stops the reorder at no point; the check makes a changed story order fail until the manifest is regenerated and the change is visible in the PR's diff.
Refines: DEMOCI-11-005
Depends on: DEMOCI-11-034
DEMOCI-11-054 MUST CI MUST record every registered scenario in-process at the base commit and at the head of a pull request that changes a recorder input. The recorder inputs are the files under vultron/demo/ and the multi-actor compose file.

Comparing head with base, not with the committed recordings, commits nothing, so no pull request regenerates a recording. Stories, fragments and checks live under vultron/demo/, and the recorder reads each cast slot's URL and default roles from the compose file (DEMOCI-11-020), so a change to either moves the recordings. A core-only pull request is not a consolidation; the daily recordings run covers its drift.
DEMOCI-11-055 MUST CI MUST compare each scenario's base and head runs on their normalized ledgers and on their check trees.

The plot manifest sees a reorder but not an edit inside a fragment. A ledger sees the protocol acts but not the checks. A check tree sees the checks but not the acts. Only both together cover what a scenario passes or fails on.
Satisfies: DEMOMA-17-002
Refines: DEMOCI-11-054
DEMOCI-11-056 MUST A scenario's check tree MUST list every demo_step, demo_check and demo_gate its run enters, in order and nested as they ran.

A check that moves into or out of a gate changes what the scenario passes or fails on and leaves the ledger byte-identical. The three context managers are the one place every check is entered, so the run sees the nesting exactly.
Refines: DEMOCI-11-055
DEMOCI-11-057 MUST Each check tree node MUST carry its kind, label, outcome and the cast members whose containers it read. A read is a GET.

A wait that reads another actor's replica has changed its subject, which EDF-06-002 constrains. Every replica read goes through the recorder's client, so the run resolves the subject, which a static reading of the source cannot. An act is not a read: counting one would name a cast member in the reads of a step that only wrote to it. The ledger trace records the acts (DEMOCI-11-055), so the two traces complement each other.
Refines: DEMOCI-11-056
DEMOCI-11-058 MUST The comparison of DEMOCI-11-055 MUST compare each scenario's verdict. The verdict is each ledger entry projected onto an explicit allow-list of fields, with each check tree node's kind, label, outcome and reads.

"Demo verdict unchanged" means the scenario did the same acts in the same order, with the same states, roles and content, and its checks reached the same outcomes. The allow-list names the fields that carry that. Bytes derived from ids, times or keys are not part of it.
Refines: DEMOCI-11-055
DEMOCI-11-059 MUST NOT The allow-list of DEMOCI-11-058 MUST NOT hold a field whose value is derived from ids, times or keys.

A timestamp, a hash-chain digest, a signature or its proof and a sender's sequence counter all change when one more clock read or id draw happens, without any change in what the scenario does. A list of noise fields to drop fails on the next derived field nobody named, as it did on the signatures of #6182 (#6194). An allow-list leaves such a field out until someone names it.
Constrains: DEMOCI-11-058
DEMOCI-11-060 MUST NOT The comparison of DEMOCI-11-055 MUST NOT rewrite an allow-listed value other than as DEMOCI-11-070 and DEMOCI-11-071 state.

Anything in the verdict that differs, such as a note's text, an added or reordered act, a changed act type, a changed state or role, or a changed check label or outcome, is a change the reviewer must see.
Refines: DEMOCI-11-055
Constrains: DEMOCI-11-058
Constrains: DEMOCI-11-070
Constrains: DEMOCI-11-071
DEMOCI-11-070 MUST The DEMOCI-11-058 comparison MUST relabel each id the run draws by its first appearance, with one mapping across a scenario's ledger and check labels.

A refactor that draws one more id shifts every later id without changing what the scenario does. One mapping across both traces keeps an id in a check label tied to the same entity as in the ledger. A cast member's actor URI is fixed by the cast (DEMOCI-11-020), so it cannot shift between two runs, and relabelling it would remove the one name in a ledger diff that says who acted.
Refines: DEMOCI-11-058
DEMOCI-11-071 MUST The comparison of DEMOCI-11-058 MUST replace each timestamp quoted inside an allow-listed string with a placeholder.

A name or a note may quote a time it was given, such as an embargo's name quoting its window. The quoted time moves with the clock, while the rest of the string is part of the verdict.
Refines: DEMOCI-11-058
DEMOCI-11-072 MUST NOT The allow-list of DEMOCI-11-058 MUST NOT leave out a state, role, status or consent field of a model that a ledger entry can carry.

An allow-list counts a field only once it is named, and these fields are what a verdict most depends on. Holding them by their shape, over the models a ledger entry can carry, means a new one fails a test rather than going uncompared.
Refines: DEMOCI-11-058
DEMOCI-11-061 MUST The comparison of DEMOCI-11-055 MUST fail, printing the difference per scenario, when a normalized ledger or check tree differs between base and head, unless the pull request is labelled demo-verdict-change (DEMOCI-11-063).

The printed difference is what lets a reviewer judge whether the change was meant.
Refines: DEMOCI-11-055
DEMOCI-11-062 MUST The comparison of DEMOCI-11-055 MUST report a run that compared no scenario as a distinct failure.

A gate that passes on an empty set passes over nothing (DF-09-009).
Refines: DEMOCI-11-055
DEMOCI-11-063 MUST A pull request labelled demo-verdict-change MUST pass the comparison of DEMOCI-11-055 when its runs differ.

A change that alters a verdict on purpose belongs in its own change (DEMOMA-17-004), and it needs a way past the gate. The label states that the change was meant.
Constrains: DEMOCI-11-061
Refines: DEMOCI-11-055
DEMOCI-11-064 MUST On a pull request labelled demo-verdict-change, the comparison job MUST print the difference to its summary.

The printed difference shows what the reviewer is approving, so the opt- out never hides the change it admits.
Refines: DEMOCI-11-063
DEMOCI-11-065 MUST The docstring of every fragment the plot manifest names MUST open with one sentence that says what the step does in CVD domain terms.

The plot manifest names fragments by code name, which a CVD domain expert cannot review. One domain sentence per fragment lets the plot render as a story a domain expert can read (DEMOCI-11-067).
Depends on: DEMOCI-11-034
DEMOCI-11-066 MUST NOT The opening sentence of DEMOCI-11-065 MUST NOT name a code identifier, a helper or a container.

A sentence in code terms is the code name again, and the rendering would be as unreadable to a domain expert as the manifest.
Constrains: DEMOCI-11-065
DEMOCI-11-067 MUST Each registered scenario's narrative page MUST include a generated numbered story of its plot after its hand-written narrative.

The rendering lets a reader check the composed story against the narrative above it. It never replaces the narrative, which is written without the code so that it can contradict it; a rendering of the code can only agree with it. Placing it after keeps the main story first.
Depends on: DEMOCI-11-034
DEMOCI-11-068 MUST The story of DEMOCI-11-067 MUST render a fragment as its docstring's opening sentence and a choice as its deciding role and presenter label.

The presenter label comes from the branch-point table (DEMOCI-11-013), so the story states each decision in the words the demo UI shows, and no label is declared a second time.
Refines: DEMOCI-11-067
Depends on: DEMOCI-11-065
DEMOCI-11-069 MUST The drift check of DEMOCI-11-005 MUST fail when a committed story rendering differs from a fresh rendering of the stories in the code.

Generating the story keeps it current only when a stale copy fails; otherwise it drifts like a hand-written list.
Refines: DEMOCI-11-005
Depends on: DEMOCI-11-067
DEMOCI-11-019 MUST A registered scenario's path MUST be read from the choices in its assembled story.

A path typed beside the story is a second copy of the same fact, and the two copies can disagree. When the path is read from the story, the registry, the scenario-tree index and the step marks in the recordings all come from the code that runs.
Implements: DEMOCI-11-014
DEMOCI-11-024 MUST NOT The @scenario decorator MUST NOT take a path parameter.

A parameter that accepts a path is the place where the second copy DEMOCI-11-019 removes would be written, and nothing would keep the two copies the same. Removing the parameter rather than refusing a scenario that uses it means the second copy cannot be written at all, so no check has to catch it.
Derives from: DEMOCI-11-019
DEMOCI-11-020 MUST Every registered scenario MUST run on one fixed cast: the same container slot, port and actor id for each cast member in every scenario of the tree.

Byte identity of a shared prefix (DEMOCI-11-018) needs more than one copy of the code. Two siblings that put the same actor in different slots record different bytes for the same story.
DEMOCI-11-025 MUST Every recording of a registered scenario MUST use the same tree-wide recording seed.

Two siblings that seed their ids with different values record different bytes for the same story, so a shared prefix cannot be byte identical (DEMOCI-11-018).
DEMOCI-11-026 MUST NOT A cast container other than the first-Vendor and first-Coordinator slots MUST NOT declare default case roles.

A character actor's CVD role comes from the act that seats it, so a container default would give it that role in every scenario and the same container could not be a Vendor in one and a Coordinator in another (DEMOCI-11-021). The first-Reporter slot and the CaseActor container are covered for a different reason: neither owns a case, so neither has a role to own one as. Only a container that can own a case declares its role (DEMOCI-11-032).
Uses definition from: DEMOCI-11-021
DEMOCI-11-027 MUST NOT A cast container's actor id MUST NOT name a CVD role.

A role-named id reads as a claim about the part its actor plays, and the cast's point is that the part changes between scenarios while the container does not (DEMOCI-11-020).
Extends: DEMOCI-11-020
DEMOCI-11-028 MUST Every cast container and the dedicated CaseActor container MUST have a seed config whose local actor is the actor that container hosts.

The seed config bootstraps a container's identity with no discovery step to fall back on, so a config naming another container's actor gives the demo two containers with one identity.
Uses definition from: DEMOCI-11-020
DEMOCI-11-029 MUST Each cast container's seed config MUST list every other cast container and the dedicated CaseActor container as a peer.

A container cannot address an actor it does not know, and the demo has no discovery step, so a missing peer stops a message that the protocol requires.
Extends: DEMOCI-11-028
DEMOCI-11-030 MUST The demo runner service MUST wait for every cast container and the dedicated CaseActor container to become healthy.

A runner that starts before a container is healthy fails the scenario's first call to it, which reads as a protocol failure.
Uses definition from: DEMOCI-11-020
DEMOCI-11-031 MUST The demo runner service MUST expose the base URL of every cast container and of the dedicated CaseActor container.

A scenario reads each container's address from its own environment variable, so a missing one resolves to the local-development default and the scenario cannot reach the actor at all.
Uses definition from: DEMOCI-11-020
DEMOCI-11-032 MUST The first-Vendor and first-Coordinator cast slots MUST declare their own CVD role as their container's default case roles.

These are the only cast containers that own a case, and a case is owned as a role (CP-01-013). Without the declaration a Coordinator that owns the case holds only case_owner, and the harness then fails every Coordinator step of the scenario (#5467, DEMOCI-11-047). Every other cast container declares none (DEMOCI-11-026).
Uses definition from: DEMOCI-11-021
DEMOCI-11-033 MUST NOT A character-actor container's seed config MUST NOT name its local actor for a CVD role.

The display name is what the devlogs and the UI show for that actor, so a role name there makes the same claim a role-named actor id would (DEMOCI-11-027), in the one place a reader looks to find out who an actor is. A fixed-role slot may be named for its role, because it plays that part in every scenario; a character actor takes the name of its container.
DEMOCI-11-021 MUST When a registered scenario seats a Reporter, a Vendor or a Coordinator, the first one of each role MUST run in the first, second or third cast slot respectively.

A fixed slot for the first Reporter, Vendor and Coordinator keeps a shared opening on the same containers in every scenario that tells it. A scenario that lacks one of these roles, such as rv with no Coordinator, leaves that slot unused. Every further cast member is a character actor that takes the role its scenario gives it, so a scenario that needs a second Vendor, a second Coordinator, a Deployer or a second Reporter adds no container.
Extends: DEMOCI-11-020

Demo CLI

Requirements for a unified demo command-line interface that aggregates all individual Vultron demo scripts into a single invokable entry point. Covers CLI structure, demo isolation, Docker packaging, and test requirements.

File ID: DC

CLI Interface

ID Priority Requirement Related
DC-01-001 MUST The unified demo MUST be implemented as a click-based CLI package at vultron/demo/cli/

One entry point in one known file gives every user and every CI job the same way to start a demo. click gives sub-commands, options and help text without custom argument code.
DC-01-002 MUST The CLI MUST provide a sub-command for each individual demo

A sub-command for each demo lets a user run one demo by name. Without it, a user must know the module path of each demo script.
DC-01-003 MUST The CLI MUST provide an all sub-command that runs every demo in sequence

The all sub-command runs every exchange demo with one command, so a user can check them all at once and find a demo that is broken.
DC-01-004 MUST The CLI MUST print a human-readable summary on completion of the all sub-command indicating which demos passed and which failed

When many demos run in sequence, the output of one demo is hard to find in the log. The summary shows which demos passed and which demo failed, so the user knows where to look.
DC-01-005 MUST Individual demo scripts MUST retain their existing if __name__ == "__main__" entry points so they remain directly invokable

A developer who works on one demo can run that script directly, without the CLI. This keeps the time to test a change to one demo short.

Demo Utilities

ID Priority Requirement Related
DC-02-001 MUST Shared demo utilities (demo_step, demo_check context managers and HTTP client helpers) MUST be extracted to vultron/demo/utils/

All demos use the same step, check and HTTP helpers. One shared module keeps their behavior and their log output the same in every demo, and a fix to a helper applies to every demo.
DC-02-002 MUST Each demo script MUST live in the vultron/demo/ package.

The CLI imports each demo as a module. When the demos are in the vultron package, the CLI, the tests and the Docker image can import them the same way, without changes to the import path.
DC-02-004 MUST Each demo script MUST be importable as vultron.demo.exchange.<script_name> or vultron.demo.scenario.<script_name>.

Exchange demos drive one backend directly, and scenario demos run several actors in containers. One sub-package for each kind keeps the two apart, and a fixed module path lets the CLI and the tests find each script by its name.
Refines: DC-02-002
DC-02-003 MUST NOT A demo MUST NOT use demo_step for an observation-only assertion block, or demo_check for an action step.

demo_step wraps an action step: it performs a side-effecting operation and puts any exception in the demo failure accumulator, so the scenario continues. demo_check wraps an observation-only assertion block: it checks state and collects assertion failures. A swap hides which steps act and which only verify, in scenario tracing, in logs and for readers.
DC-02-005 MUST NOT A demo_check block MUST NOT perform a side-effecting operation.

A demo_check failure is recorded and the scenario continues. If the block also changed state, a failed check could leave that change half done, and the trace would not show the change as an action step.
Refines: DC-02-003

Demo Isolation

ID Priority Requirement Related
DC-03-001 MUST Each demo MUST include setup and teardown logic that leaves the DataLayer in a clean state after the demo completes

A demo that leaves records in the DataLayer can change the result of the next demo or the next run. A clean state after each demo makes each run repeatable.
DC-03-002 MUST NOT Demos that the all sub-command runs in sequence MUST NOT share mutable state.

When demos share mutable state, the result of one demo depends on the demos that ran before it. Then a demo can pass in all and fail alone, or the reverse.
DC-03-004 MUST Each demo that the all sub-command runs MUST operate on a freshly initialized DataLayer context.

A fresh DataLayer context for each demo is how the demos avoid shared state. It makes each result independent of the order in which the demos run.
Implements: DC-03-002
DC-03-003 MUST NOT The CLI MUST NOT assume a globally pre-initialized DataLayer.

A demo that depends on a DataLayer it did not create works only when something else prepared that DataLayer first.
DC-03-005 MUST Each demo invocation MUST create and clean up its own DataLayer context.

When each demo creates and cleans up its own context, the demo works the same from the CLI, from a test and from Docker, and leaves nothing for the next run.
Implements: DC-03-003

Docker Packaging

ID Priority Requirement Related
DC-04-001 MUST The unified demo MUST be packaged as a Docker service (demo service in docker/docker-compose.yml)

A Docker service lets a user run the demos against the containerized API without a local Python environment.
DC-04-002 MUST The Docker entry point MUST launch the unified CLI so that the container runs interactively and shows the list of demos and how to run one

A user who starts the demo container sees a list of the demos and how to run one. The user does not need to know the sub-command names before they start.
DC-04-003 MUST Individual per-demo Docker services (one service per demo script) MUST be removed from docker-compose.yml once the unified demo service is operational

One Docker service for each demo repeats the same configuration many times, and the copies can become different. With one unified service, there is only one configuration to keep correct.

Unit Testing

ID Priority Requirement Related
DC-05-001 MUST The unified CLI MUST have unit tests in test/demo/test_cli.py

The CLI is the entry point for every demo. Unit tests in a known location find errors in the way the CLI connects sub-commands to demos before a user or a CI job runs the demos.
DC-05-002 MUST Unit tests for the all sub-command MUST mock or stub the individual demo functions and verify that every registered demo is invoked exactly once in the expected order

A real demo needs a running API, so a unit test that runs real demos is slow and can fail for reasons outside the CLI. Stubs let the test check only the CLI behavior: all calls each registered demo one time, in order.
DC-05-003 MUST Unit tests MUST verify that the CLI exits with a non-zero status code when any demo sub-command raises an exception

CI and scripts use the exit status to decide if the demos passed. If the CLI exits with zero after a demo fails, the failure is not seen.
DC-05-004 MUST Unit tests for each sub-command MUST verify the sub-command invokes the correct underlying demo function

If a sub-command calls the wrong demo function, the user runs a different demo than the one they selected, and the output can still look correct. A unit test for each sub-command finds this error.

Integration Testing

ID Priority Requirement Related
DC-06-001 SHOULD An integration test script SHOULD exist at integration_tests/demo/run_demo_integration_test.sh (or equivalent Python script) that: 1. Starts the api-dev service and waits for it to be healthy 2. Runs the unified demo all sub-command inside the demo container 3. Verifies all demos complete without errors

Unit tests stub the demos, so they do not show that the demos work against a real API. An integration test that starts the API and runs all demos in the container checks the full setup that a user runs.
DC-06-002 MUST A integration_tests/README.md MUST document how to run the integration tests and what success looks like

The integration tests need Docker and a specific sequence of steps. Without written instructions, a developer cannot run them or tell a pass from a failure.
DC-06-003 SHOULD The integration test SHOULD be runnable via a Makefile target (e.g., make integration-test)

A Makefile target gives one short command that is easy to remember, so a developer does not need to know the script path.

Demo Scenario Report Tool

Requirements for a read-only command-line tool that parses the JSONL case-ledger replica files produced by demo scenario runs and renders a selective, human-readable report of who did what, with what activity, and in what order. Covers input discovery, the distilled intermediate data model, markdown and HTML rendering, the per-actor replica-presence matrix, friendly naming, and test requirements.

File ID: DRPT

Tool Structure and Invocation

ID Priority Requirement Related
DRPT-01-001 MUST The report tool MUST be a standalone package at vultron/demo/report/, importable as vultron.demo.report.

A standalone module keeps the read-only reporting utility decoupled from the demo-run CLI (DC-01) while remaining colocated with the demo code that produces the ledger files.
DRPT-01-006 MUST The vultron.demo.report module MUST provide an if __name__ == "__main__" entry point, so that python -m vultron.demo.report runs the tool.

A direct entry point lets a developer run the report on a devlogs directory without installing the package and without the demo CLI.
Extends: DRPT-01-001
DRPT-01-002 MUST The tool MUST accept an input directory path. Without one, it uses the DEVLOGS_DIR environment variable, or devlogs/ under the repository root when that variable is unset.

The demo run writes each replica under DEVLOGS_DIR, and the invariant checks in test/ci/invariants/ read the same place. When the tool uses the same default directory, it reads the output of a demo run with no extra arguments.
DRPT-01-007 MUST The tool MUST discover its input files by a recursive glob of **/*-case-ledger.jsonl beneath the input directory.

The demo run writes each replica to {DEVLOGS_DIR}/{demo_name}/{actor_name}/{case_id_slug}-case-ledger.jsonl. The same file pattern finds every replica of a run, and it does not read the other files in the directory.
Extends: DRPT-01-002
DRPT-01-003 MUST The tool MUST derive each entry's actor name from the name of the directory that contains its JSONL file (e.g. reporter, vendor, case-actor).

A ledger entry is the same in every replica, so it does not show which actor's replica holds it. The demo run writes the replica of each actor into a directory with the name of that actor. Thus the directory name is a reliable source for the actor name.
DRPT-01-004 MUST The tool MUST exit with status code 0 on success and a non-zero status code when the input directory is missing, contains no matching JSONL files, or a file cannot be parsed.

Scripts and CI jobs use the exit status to decide if the report was made. If the tool exits with zero when it has no input or cannot parse a file, a missing or damaged report is not seen.
DRPT-01-005 SHOULD The tool SHOULD also have a vultron-demo-report console-script entry point in the [project.scripts] table of pyproject.toml that resolves to vultron.demo.report:main.

A console script matches the other demo entry points (vultron-demo, vultrabot_*), and a user can run the tool after install without python -m.
Extends: DRPT-01-001
DRPT-01-008 MUST vultron.demo.report:main MUST run when it is called with no arguments, and then read its arguments from sys.argv.

The console-script wrapper calls main() with no arguments. A main that needs an argument fails as soon as the console script starts.
Extends: DRPT-01-005
DRPT-01-009 MUST vultron.demo.report:main MUST return the process exit code.

The console-script wrapper uses the return value of main() as the exit status. A main that returns no code cannot report a failure.
Extends: DRPT-01-005

Distilled Timeline Model

ID Priority Requirement Related
DRPT-02-001 MUST The tool MUST define a first-class pydantic.BaseModel (v2) distilled event type, such as CaseTimelineEvent, for one canonical timeline event in friendly-readable form.

One typed model between the parser and the renderers keeps the JSONL parsing details in one place, and a test can check the parsed events without a renderer.
DRPT-02-014 MUST The markdown renderer and the HTML renderer MUST consume the distilled event model, not raw JSONL dicts.

When both renderers read the same typed model, they show the same fields with the same meaning. A renderer that reads raw dicts repeats the parsing and can drift from the other renderer.
Depends on: DRPT-02-001
DRPT-02-002 MUST Each distilled event MUST surface, where available in the source entries: the acting actor, the semantic type (or extracted message semantics), the target object reference, the timestamp (receivedAt), the resulting RM/EM/CS state transition(s) from the payload snapshot, the log_index, and a short (truncated) entry_hash for chain traceability.

A reader of the report must see who did what, to which object, when, and what case state changed as a result. The log_index and a short entry_hash let a reader find the matching entry in the ledger files.
DRPT-02-003 MUST The parser MUST tolerate both camelCase and snake_case field spellings in source entries (e.g. logIndex/log_index, entryHash/entry_hash, payloadSnapshot/payload_snapshot), consistent with the tolerance already present in test/ci/invariants/common.py.

Ledger files can spell the same field in camelCase or in snake_case. If the parser reads only one spelling, it drops data, with no error, from files that use the other one, and the report shows an incomplete case.
DRPT-02-004 MUST The tool MUST merge the entries of all discovered actors into a single canonical timeline, and de-duplicate replicated entries by entry_hash.

Replicas hold copies of the same canonical entries; de-duplication yields the single case story rather than N near-identical per-actor logs.
DRPT-02-015 MUST The tool MUST order the canonical timeline by log_index ascending.

log_index is the order in which the CASE_MANAGER committed the entries. A timeline in that order tells the case story in the sequence it happened.
Extends: DRPT-02-004
DRPT-02-005 MUST For each canonical timeline event, the tool MUST compute a per-actor replica-presence indicator recording which discovered actors' replicas contain that entry (by entry_hash), so replica convergence and divergence are visible at a glance.

Each actor holds a replica of the case ledger. If a replica does not contain an entry, that actor has not received that case event. The presence indicator for each actor shows these gaps without a manual comparison of the files.
DRPT-02-006 MUST When the discovered entries span more than one case (distinct case_id values — as when the default devlogs/ root accumulates multiple demo runs), the tool MUST partition the timeline by case_id.

log_index restarts at 0 for each case and same-named actor directories recur across demo runs, so a single merged timeline over multiple cases interleaves unrelated events and conflates replica presence across cases. DRPT-02-004's "single canonical timeline" is well-defined only within one case; partitioning by case_id preserves that guarantee when the input directory holds more than one.
Extends: DRPT-02-004
DRPT-02-009 MUST When the discovered entries span more than one case, the tool MUST NOT interleave events from different cases.

Interleaving events from distinct cases produces a meaningless merged timeline because log_index is case-local and replica presence is case-specific.
DRPT-02-010 MUST The distilled event model MUST carry the case_id field.

Downstream partitioning and per-case rendering require each event to identify which case it belongs to.
DRPT-02-011 MUST The tool MUST group timeline events by case_id, so that the events of each case are contiguous.

Case-contiguous ordering prevents a comparison of log_index values across cases, because log_index is case-local.
DRPT-02-016 MUST Within each case group, the tool MUST order events by log_index ascending.

The log_index order within a case keeps the causal sequence of that case.
Extends: DRPT-02-011
DRPT-02-012 MUST The replica-presence matrix MUST be computed per case.

Replica presence is meaningful only within a single case; computing it across cases conflates unrelated actor participation.
DRPT-02-013 MUST Each renderer MUST present one clearly labelled section (or table) per case.

Separate per-case sections make case boundaries visible to the reader and prevent misinterpretation of per-case metadata such as time range and replica presence.

Friendly Naming

ID Priority Requirement Related
DRPT-03-001 MUST Human-readable output MUST render actors and target objects by short, friendly names, such as "Reporter", "report" or "note".

A reader can follow "Reporter submitted report" at a glance. A reader cannot follow a long URI or a UUID in the same position.
DRPT-03-009 MUST NOT An event summary MUST NOT use a bare URI or an opaque UUID identifier as its primary noun.

A URI or a UUID as the subject or object of a summary hides who did what. The friendly name of DRPT-03-001 goes in that position instead.
Derives from: DRPT-03-001
DRPT-03-010 SHOULD The tool SHOULD derive actor labels from the actor directory name.

The demo run writes the replica of each actor into a directory with the name of that actor (DRPT-01-003). That name is short and reads as a role, such as reporter or vendor.
Implements: DRPT-03-001
DRPT-03-011 MAY Human-readable output MAY keep a full identifier as secondary detail, such as a tooltip, a title attribute or a trailing reference column.

The full identifier stays available as secondary detail, so a reader can still find the exact object while the summary uses its friendly name.
DRPT-03-003 MUST The tool MUST build a URI-to-display-name map during timeline construction by scanning all payload snapshots for actor objects (type Organization, Person, Service, Application, Group, Actor) that carry both an id (URI) and a non-empty name field.

Actor URIs may be UUID-based when the actor was created with a generated identifier rather than a slug. Without name resolution, friendly_actor_name produces labels like "A1e7 421f B727" that violate DRPT-03-009's prohibition on opaque identifiers. The name field is present on inline actor objects in wire payloads (e.g. Organization objects in Invite or Accept activities), making payload-scan the correct extraction point.
Implements: DRPT-03-001
DRPT-03-002 MUST Event summaries MUST map the semantic type to a concise active-voice phrase (subject verb object) by looking up the matching SemanticEntry in SEMANTIC_REGISTRY and rendering entry.phrase via str.format_map().

SEMANTIC_REGISTRY already holds a phrase for each message semantic (SE-07-001). When the tool uses that phrase, every semantic in the registry has a summary, and the summary cannot become different from the registry.
DRPT-03-004 MUST When it renders a phrase template, the tool MUST fill the {actor}, {object} and {target} slots from the resolved display labels of the event record.

The resolved display labels are the friendly names of DRPT-03-001. Slots filled from them give a summary such as "Reporter submitted report".
Extends: DRPT-03-002
DRPT-03-012 MUST The tool MUST render a missing slot, such as {context} when no context was recorded, as an em-dash ("—") instead of raising a KeyError.

CaseLedgerEventRecord is constructed from JSONL data and may not carry all slot values present in a live VultronEvent. A defaultdict fallback ensures phrases for multi-party semantics (e.g. {actor} invited {object} to {target}) degrade gracefully to "{actor} invited {object} to —" when the destination is absent rather than surfacing a runtime error.
Extends: DRPT-03-004
DRPT-03-005 MUST The tool MUST NOT maintain a local phrase table parallel to the SEMANTIC_REGISTRY.

A local duplicate phrase table diverges from the registry over time; prohibiting it ensures all phrase coverage comes from SemanticEntry definitions per SE-07-001.
DRPT-03-006 MUST When no SEMANTIC_REGISTRY entry exists for a semantic type (e.g. data from a future protocol version), the tool MUST fall back to a humanized form of the raw semantic-type string.

Graceful fallback prevents rendering failures when new semantic types are introduced before the registry is updated.
DRPT-03-007 MUST Actor labels MUST use the resolved display name from the URI-to-display-name map when available.

Resolved display names prevent opaque UUID-based actor labels in output, satisfying DRPT-03-009's prohibition on bare identifiers.
DRPT-03-008 MUST Actor labels MUST fall back to the URI path-segment heuristic only when no entry is found in the URI-to-display-name map.

The heuristic fallback provides a best-effort human-readable label for actors whose name was not captured in any payload snapshot.

Rendering

ID Priority Requirement Related
DRPT-04-001 MUST The tool MUST render a markdown table report (one row per canonical timeline event) covering the distilled fields, including a per-actor replica-presence matrix column group.

A markdown table is easy to read in a terminal, on GitHub and in a CI log. One row for each event, with the presence of each actor in columns, shows the case history and the replica gaps together.
DRPT-04-002 MUST The tool MUST render a self-contained static HTML report file with all styling inlined (no external CSS, JS, fonts, or network assets), so the artifact renders identically offline and can be archived or shared as a single file.

A report with no external assets shows the same content offline, in a CI artifact or in an archive. The tool writes the HTML in Python, so the report needs no JavaScript build step, its output is deterministic, and tests can check it.
DRPT-04-003 MUST In the HTML report, the per-actor replica-presence matrix MUST be rendered as a per-actor checkbox/emoji cell per event, showing a present/absent indicator for each actor column (e.g. an event present in three of four actors' replicas shows three checks across four columns).

A check mark or an empty cell for each actor shows at a glance which replicas contain an event. A count alone does not show which actor is missing it.
DRPT-04-004 MUST The tool MUST let the user select the output format, for example with --format markdown&#124;html.

Different readers need different formats: markdown for a terminal or for GitHub, and HTML for a browser.
DRPT-04-017 MUST The tool MUST write the report to a file at a configurable path.

A report written to a file can be kept as a CI artifact or shared after the run. A configurable path lets a CI job put it where the artifact upload looks.
DRPT-04-005 SHOULD After it writes an HTML report, the tool SHOULD open the report in the default browser with webbrowser.open().

A user who runs the tool on a desktop wants to see the report at once.
DRPT-04-018 MUST The tool MUST provide a flag, such as --no-open, that suppresses the browser launch.

In CI and in other non-interactive runs there is no browser, so a run must be able to stop the launch.
Extends: DRPT-04-005
DRPT-04-006 SHOULD Each per-case section SHOULD display the time range of its events as Time range: {first} – {last}, where {first} and {last} are the minimum and maximum receivedAt timestamps (full ISO 8601 strings) among the case's canonical events.

When reviewing reports from CI runs or comparing across scenarios, knowing the time range at a glance (e.g. "15:31:20Z – 15:31:27Z") is more useful than counting rows. Per-case placement is necessary because log_index restarts at 0 per case and cases may span non-overlapping time windows (DRPT-02-006).
Extends: DRPT-04-001
Extends: DRPT-04-002
DRPT-04-007 MUST The Time column header MUST be labelled "ΔT".

Absolute timestamps repeat the date and timezone on every row, making it hard to see the pacing of events. A delta-T column lets readers immediately spot where the protocol paused or accelerated. DRPT-04-006 already provides the absolute-time anchor (first/last timestamps in the section header), so the table body can omit redundant full timestamps without losing traceability.
Extends: DRPT-04-001
Extends: DRPT-04-002
DRPT-04-008 MUST The time range line MUST be omitted when no events in the case carry a receivedAt timestamp.

Rendering a time range with no data would display a meaningless or error-prone placeholder.
DRPT-04-009 MUST When all events in a case share the same receivedAt timestamp, both time range bounds MUST be shown ({ts} – {ts}).

Showing both bounds even when equal makes the format unambiguous and avoids special-casing that could hide single-event cases.
DRPT-04-010 MUST In markdown output, the time range MUST appear as a bullet line between the case heading and the event table.

Consistent placement ensures the time range is visible as a section-level annotation rather than embedded in the table.
DRPT-04-011 MUST In HTML output, the time range MUST appear as a <p class="meta"> element between the <h2> heading and the <table>.

The meta class allows consistent styling of section-level metadata across cases in the HTML report.
DRPT-04-012 MUST Each Time cell MUST display a delta from the previous row's receivedAt timestamp as an adaptive duration string: +Ns when under 60 seconds, +Nm Ns when under one hour, and +Nh Nm Ns for one hour or more (no day component).

Adaptive formatting makes small and large deltas equally readable without wasting space on zero-valued time components.
DRPT-04-013 MUST The first row that carries a receivedAt timestamp MUST show +0s in the Time cell.

The first timed row anchors the delta sequence; showing +0s makes the anchor explicit rather than leaving the first cell empty.
DRPT-04-014 MUST Rows without a receivedAt value MUST show — in the Time cell.

An em-dash distinguishes missing-timestamp rows from rows with a genuine zero delta.
DRPT-04-015 MUST In the HTML renderer, the full ISO 8601 receivedAt string MUST be retained as a title= tooltip on the Time <td> element.

The tooltip preserves the absolute timestamp for hover inspection without cluttering the table cell.
DRPT-04-016 MUST In the markdown renderer, the absolute receivedAt timestamp MUST NOT appear in the Time column table cell body.

The per-case time-range line (DRPT-04-006) provides the absolute-time anchor; repeating full timestamps in every cell is redundant.

Testing

ID Priority Requirement Related
DRPT-05-001 MUST Unit tests MUST cover JSONL-to-distilled-model parsing against fixtures that include both camelCase and snake_case field spellings.

The parser is the part of the tool that is most likely to lose data without an error. Fixtures with both field spellings find a spelling the parser drops.
DRPT-05-008 MUST Unit tests MUST assert field extraction, merge and de-duplication by entry_hash, and the per-actor replica-presence computation.

Checks of extraction, merge and presence find the data loss that a renderer test cannot see.
Extends: DRPT-05-001
DRPT-05-002 MUST Unit tests MUST cover both renderers: given a fixed list of distilled events, assert the markdown table structure and assert that the HTML output is well-formed and self-contained (references no external assets).

The renderers produce the output that a reader sees. Fixed input events let a test check the table structure and the self-contained HTML (DRPT-04-002) without a demo run.
DRPT-05-003 MUST A CLI smoke test MUST invoke the entry point against a tiny fixture directory, assert exit code 0, assert an output file is written, and assert that --no-open suppresses any browser launch.

The unit tests call functions directly. A smoke test of the entry point checks the parts that a user runs: argument parsing, the exit status, the output file, and the flag that stops the browser launch.
DRPT-05-004 MUST Unit tests MUST cover actor name resolution (DRPT-03-003): assert that collect_actor_names extracts URI-to-name mappings from inline actor objects in payload snapshots, that build_timeline populates actor_display_name on events whose actor URI is in the map, and that actor_label returns the display name rather than a hex-fragment label for UUID-based actor URIs.

Name resolution has three steps: collect the names, set them on the events, and use them in the label. If one step fails, the label falls back to a hex fragment of the UUID, and the report still renders. A test of each step finds the step that failed.
Verifies: DRPT-03-003
DRPT-05-005 MUST Unit tests MUST cover the _format_delta helper directly: assert +0s when prev_received_at is None and received_at is set (first-row anchor), assert — when received_at is None, assert — when both are None, and assert correct adaptive formatting for sub-minute (+Ns), sub-hour (+Nm Ns), and multi-hour (+Nh Nm Ns) deltas.

The delta format has several cases: the first row, missing timestamps, and three ranges of duration. A direct test of _format_delta checks each case, including the cases that a fixture with real events does not reach.
Verifies: DRPT-04-012
Verifies: DRPT-04-013
Verifies: DRPT-04-014
DRPT-05-006 MUST Renderer tests MUST assert that the Time column in the table body contains delta strings (e.g. +0s) rather than ISO 8601 timestamps.

Verifies that neither renderer leaks absolute timestamps into the Time cell body, per DRPT-04-016.
DRPT-05-007 MUST HTML renderer tests MUST assert that the full ISO 8601 receivedAt timestamp is retained as a title= tooltip on the Time <td> element.

Verifies DRPT-04-015: the absolute timestamp is preserved for hover inspection even though it does not appear in the cell body.

Reading a Case Ledger File

The demo report tool and the demo UI's Log Replay mode (ui/) both read a case ledger JSONL file. Both refuse a line that is not a JSON object. Log Replay also checks each entry's envelope against the model. The report tool does not: it degrades a malformed field in one row rather than lose the rest of the run.

ID Priority Requirement Related
DRPT-06-001 MUST A ledger replay or report tool MUST name to the user each line that is not a JSON object, and replay none of that line.

A line that is not a JSON object holds no entry to read. Dropping it without notice makes the output show a case history the file does not hold; naming it tells the user where the file is damaged.
Extends: DRPT-01-004
DRPT-06-002 MUST Log Replay MUST hold a ledger entry's envelope to the case ledger model, and a received status in payloadSnapshot only to the parse edge (MV-11-003). The envelope check requires each field the model always writes and refuses an undeclared key.

The envelope is written by the CASE_MANAGER, so a missing field or an unknown key means the line is not a ledger entry this model wrote. Log Replay refuses such a line rather than replay it with defaults, which would show events that never happened. A received status is the sender's content carried as received, and the parse edge sets aside an unknown key in it rather than refusing it; a stricter viewer would refuse lines the protocol accepted.
Refines: DRPT-06-001
Depends on: MV-11-003

Dispatch Routing

After semantic extraction, the dispatcher routes VultronEvent domain objects to the appropriate use-case class. The dispatcher may execute use cases synchronously (DirectActivityDispatcher) or asynchronously (queue-based).

File ID: DR

Dispatcher Protocol

ID Priority Requirement Related
DR-01-001 MUST All dispatcher implementations MUST implement ActivityDispatcher protocol

Driving adapters, such as the inbox, call the dispatcher only through the ActivityDispatcher port. If all implementations obey that protocol, an adapter or a test can replace one dispatcher with a different one without a code change.
DR-01-002 MUST Dispatchers MUST construct use-case instances with the complete VultronEvent and DataLayer before calling execute(), so that execute() takes no arguments

A use case gets its event and its DataLayer at construction, and has one fixed entry point, execute(). Thus the dispatcher can run all use cases in the same way. A test can also build a use case with a fake DataLayer and run it without a dispatcher.
DR-01-003 MUST Dispatchers MUST perform semantic type validation at dispatch time using the configured semantics-to-use-case mapping

The dispatcher routes on the semantic type, from the one configured mapping. Thus each event goes to the use case that handles its meaning. If a dispatcher chose by other fields, or kept its own table, it could send the same message to different handlers.
Implements: HP-02-001

Handler Lookup

ID Priority Requirement Related
DR-02-001 MUST The system MUST look up use-case classes by semantic type using the mapping returned by use_case_map()

use_case_map() derives the routing table from the semantic registry. The registry is the one location that ties a message meaning to its use case. When the dispatcher reads routes from the registry, the two agree about which use case handles each message.
Implements: HP-03-001
DR-02-002 MUST The mapping returned by use_case_map() MUST contain an entry for every MessageSemantics value whose SEMANTIC_REGISTRY entry names a use case, and none for a value the registry recognizes but no use case handles (SE-05-002)

A missing entry leaves a handled meaning with no route. An extra entry routes a meaning that no use case claims. When the map agrees with the registry entries, each handled message has a route. Each unhandled message gets the refusal "no use case found".
Derives from: SE-05-002

Direct Dispatch Implementation

ID Priority Requirement Related
DR-03-001 MUST The DirectActivityDispatcher MUST execute handlers synchronously

The direct dispatcher is the in-process implementation. The caller already runs in a background task. When the use case runs in the same call, the caller gets the result of the handler and any exception. The caller then decides the inbox outcome.
DR-03-002 MUST The DirectActivityDispatcher MUST let every exception a handler raises propagate to its caller, uncaught. A semantic type with no use case raises nothing: the dispatcher reports it as a REFUSED "no use case found" verdict, logged at INFO (SE-05-005).

Catching and logging belongs at the adapter boundary that decides what a failure means for the inbox item (IE-06-004), not in core: a blanket catch in the dispatcher would break CS-23-001 (no broad except outside a BT node's update()) and HP-05-001 (handlers raise for unrecoverable errors), and would turn a programming error into a silent verdict. The dispatcher routes by semantics alone; an activity missing a slot its event requires, such as its case, never reaches it, because extraction refuses it first (ARCH-10-001).
Refines: CS-23-001
Uses definition from: SE-05-005

Async Dispatch Implementation

ID Priority Requirement Related
DR-04-001 SHOULD An async dispatcher SHOULD queue activities for processing

A queue lets the inbox accept a message and return immediately, and the handlers run later. The queue also absorbs bursts of messages, so the receiver does not block.
DR-04-002 SHOULD An async dispatcher SHOULD process activities in FIFO order

Many protocol messages depend on earlier messages, for example a reply to an offer, or a status update after a participant joins. When the receiver processes messages in arrival order, it does not handle a message before the message that it follows.

Docs Site Build and Publication Workflows

Requirements for the GitHub Actions workflows that build the MkDocs site and publish it: the review workflow .github/workflows/docs-build-check.yml, which runs on pull requests and verifies the site builds cleanly and that its links and URLs resolve, and the publication workflow .github/workflows/deploy_site.yml, which builds the site and uploads it to GitHub Pages. DOCBW-01, DOCBW-02 and DOCBW-05 name and configure the review workflow; DOCBW-03 states the build and gate obligations every site-building workflow carries; DOCBW-06 states what is specific to publication; DOCBW-07 states the release promotion, release tag check and staleness alarm that read the publication's tags; DOCBW-08 states how each released draft of the Protocol Specification is frozen at promote and served by every build. The workflows are distinct from python-app.yml (Python unit tests and linting) and .github/workflows/demo-integration.yml (demo container integration tests, specified in specs/demo-ci.yaml).

File ID: DOCBW

Review Workflow File Name and Display Name

ID Priority Requirement Related
DOCBW-01-001 MUST The workflow file MUST be named .github/workflows/docs-build-check.yml.

Another workflow calls this workflow by its file path, and specs, tests and documentation refer to it by that path. A fixed file name keeps those calls and references correct.
DOCBW-01-002 MUST The workflow name: field MUST be Docs Build and Link Check.

GitHub shows the name: field in the Actions tab and in the checks list of a pull request. A fixed name lets maintainers find the docs check in those lists.

Trigger Conditions

ID Priority Requirement Related
DOCBW-02-001 MUST The workflow MUST trigger on pull_request events whose changed paths include at least one of: docs/**, overrides/**, mkdocs.yml, pyproject.toml, uv.lock, vultron/**, specs/**, the gates' composite action (.github/actions/check-site-publication/**), the shared build action and the environment action it calls (.github/actions/build-site/**, .github/actions/setup-python-uv/**), or the workflow file itself (.github/workflows/docs-build-check.yml).

A page renders from more than its docs/ file. mkdocstrings reads vultron/, exec blocks print vultron/ examples and the output of generators, and the spec reference pages render specs/*.yaml. If the trigger leaves out one of these paths, a change there can break the site while this workflow does not run. Changes only to plan/, notes/ or other markdown outside the site do not change the built site, so they do not trigger the workflow (DOCBW-02-003). A change the filter misses is still checked by the deploy (DOCBW-03-012).
DOCBW-02-002 MUST The workflow MUST trigger on workflow_dispatch events to allow manual runs at any time.

The workflow has no push trigger, so it runs only on a pull request that changes a watched path. A maintainer sometimes needs the docs check when there is no such pull request, for example to check a branch or main directly.
DOCBW-02-003 MUST NOT The pull_request trigger MUST NOT use **/*.md as a path pattern, as this would cause the workflow to run on changes to plan/, notes/, and other non-site markdown files that have no effect on the published documentation.

Most markdown in the repository is not part of the site. A run for each change to plan/ or notes/ uses CI time and adds a check that tells the reader nothing about the site.

Job Structure

ID Priority Requirement Related
DOCBW-03-001 MUST The workflow MUST contain a single job that runs both the build-site and link-check phases sequentially, sharing the same runner filesystem to avoid artifact upload/download overhead.

The link check reads the site/ tree that the build makes. In one job, both phases use the same file system, so the workflow does not upload and download the site as an artifact. This makes the run shorter and removes a step that can fail.
DOCBW-03-002 MUST The Build Site step MUST run on every workflow trigger regardless of which paths changed, so that Python-macro and plugin failures introduced by pyproject.toml or mkdocs.yml changes are always caught.

A change to pyproject.toml or mkdocs.yml can break a macro or a plugin on any page, whatever docs paths changed. If the build step ran only for some paths, the workflow could pass while the site does not build.
DOCBW-03-004 SHOULD The workflow SHOULD validate that maintainer-focused docs remain buildable. Pages under docs/developer/ are declared as draft_docs in mkdocs.yml and are served by mkdocs serve but excluded from production builds; CI validates the production build only.

Maintainers read the pages under docs/developer/ with mkdocs serve, so a broken page there misleads them. mkdocs build leaves out draft pages, so the production build in CI does not check them.
DOCBW-03-005 MUST A withheld-artifact step MUST run after the Build Site step and fail the workflow when any artifact declared withheld produced files in site/.

A decision not to publish an artifact is a claim, and only the build output shows if the claim is true. A key that looks like a suppression can have no effect on the build. For example, draft: true is a key of the Material blog plugin, not of MkDocs, so a page with it still gets to site/. A check of the output, not of the mkdocs.yml mechanism, also finds a pattern that matches the wrong path.
DOCBW-03-016 MUST The withheld-artifact step MUST also fail when site/ is absent or empty, and when a withheld declaration matches no file in the source tree.

With no site/, or with a declaration that matches nothing, the step has nothing to check and would pass. A gate that finds no targets and passes is worse than no gate (DF-09-009).
Extends: DOCBW-03-005
DOCBW-03-006 MUST Every workflow that builds the site MUST run the DOCBW-03-005 step, including .github/workflows/deploy_site.yml.

deploy_site.yml is the workflow that actually publishes: it builds site/ from a scheduled, manual, release or rollback run (DOCBW-06-007) and uploads it to Pages. A gate present only in the pull-request workflow does not bind the publishing path, so a withheld artifact on a commit the publish takes without a pull request (a direct push to main, or a rollback to an older tag), or one a plugin or dependency change brings into the build, would ship.
Extends: DOCBW-03-005
DOCBW-03-007 MUST A reference-axis step MUST fail the workflow when any internal reference in the built site/ tree resolves to a path the build did not produce.

An internal reference can have a correct form and still point to a path that the build did not make, for example after its target moves to draft_docs. --strict cannot see every such reference, because markdown-exec renders on a child Markdown instance that has no relative-link treeprocessor. A check of resolution also covers form checks such as a .md suffix. Other clauses: notes/documentation-strategy.md.
DOCBW-03-017 MUST The reference-axis step MUST run after the Build Site step on every trigger, with no step-level if: condition.

The step reads site/, so before the build it has nothing to check. A step that an if: can skip lets a dead reference merge on any trigger the condition excludes.
Extends: DOCBW-03-007
DOCBW-03-018 MUST The reference-axis step MUST evaluate every built HTML file rather than only those reachable from an entry page.

A crawl from an entry page misses every page that no page links to, and a dead reference on such a page still reaches readers who arrive from a search or a bookmark.
Extends: DOCBW-03-007
DOCBW-03-019 MUST The reference-axis step MUST fail when site/ is absent or empty.

With no built files the step checks no reference and would pass. A gate that finds no targets and passes is worse than no gate (DF-09-009).
Extends: DOCBW-03-007
DOCBW-03-020 MUST The reference-axis step MUST run in every workflow that builds the site, on the same terms as DOCBW-03-006.

A check present only in the pull-request workflow does not bind the publishing path, so a dead reference on a commit that reached main without a pull request, or on an older commit a rollback redeploys, would ship.
Extends: DOCBW-03-007
Uses definition from: DOCBW-03-006
DOCBW-03-008 MUST A continuity step MUST fail the workflow when a URL that an earlier publish served reaches no built page, directly or through a redirect chain. A URL that a withheld declaration (DOCBW-03-005) covers is exempt.

Readers and other sites keep links to the URLs that an earlier publish served. When a page moves or is withdrawn with no redirect, each of those links gets a 404. --strict checks links in one build, not URLs that an earlier build served. A withdrawn page is excluded, not redirected, so a retirement does not look like a move. Other clauses: notes/documentation-strategy.md.
Uses definition from: DOCBW-03-005
DOCBW-03-021 MUST The continuity step MUST run after the Build Site step.

The step reads site/, so before the build it has nothing to check.
Extends: DOCBW-03-008
DOCBW-03-022 MUST This codebase MUST commit the record of URLs that earlier publishes served.

The evidence of what a publish served, the deployed site, is gone when the next deploy replaces it, so only a committed copy keeps it.
Extends: DOCBW-03-008
DOCBW-03-023 MUST The record of served URLs MUST only grow.

A URL dropped from the record is no longer checked, so a later publish can turn it into a 404 with no failing check.
Extends: DOCBW-03-022
DOCBW-03-024 MUST NOT The continuity step MUST NOT derive the record at check time from the branch the publish replaces.

That ref holds only the last publish, and the next publish replaces it. A record derived from it at check time loses every URL that an older publish served.
Extends: DOCBW-03-008
DOCBW-03-025 MUST The continuity step MUST fail when site/ is absent or empty or the record is empty.

With no built site or no recorded URL the step checks nothing and would pass. A gate that finds no targets and passes is worse than no gate (DF-09-009).
Extends: DOCBW-03-008
DOCBW-03-026 MUST The continuity step MUST run in every workflow that builds the site, on the same terms as DOCBW-03-006.

A check present only in the pull-request workflow does not bind the publishing path, so a commit that reached main without a pull request and breaks a served URL would ship.
Extends: DOCBW-03-008
Uses definition from: DOCBW-03-006
DOCBW-03-009 MUST Every workflow that builds the site MUST run mkdocs build --strict, so that any warning the build emits fails the workflow.

mkdocs.yml raises dead in-page anchors, and pages that are in neither the nav nor not_in_nav, to warn, so that a strict build fails on them (DOCBW-03-011). If a workflow builds without --strict, the warnings print and the job stays green. Strict mode does not cover every link. --strict sees only the links that MkDocs parsed, so DOCBW-03-007 checks the built output.
DOCBW-03-010 MUST NOT A site build that DOCBW-03-009 requires to be strict MUST NOT also pass --quiet (or -q).

--quiet raises the mkdocs logger to ERROR before strict mode's warning counter sees a record, so mkdocs build --strict --quiet exits 0 over warnings. The flag reads as cosmetic and switches the gate off.
Extends: DOCBW-03-009
DOCBW-03-011 MUST mkdocs.yml MUST set validation.links.anchors and validation.nav.omitted_files to warn, so that a strict build fails on a dead in-page anchor link and on a page absent from both the nav and not_in_nav.

info is below what --strict counts, so downgrading either setting turns its check off as silently as dropping --strict would, and nothing in the build output says so.
DOCBW-03-012 MUST Every workflow that builds the site MUST run, after the Build Site step and on the same terms as DOCBW-03-006, a step that fails when a page the checked-out commit builds is absent from the DOCBW-03-008 record of served URLs, deciding which pages are built by the same rule that extends the record.

A page goes live at the next deploy after it reaches main, whatever triggers that deploy, so it is recorded in the pull request that adds it, while its author is at hand, instead of in a catch-up before a release. Each docs pull request is checked at its merge result, and the deploy re-checks the commit it ships, covering a change the review's path filter missed. The record has one kind of entry, so a page counts as served once it is recorded: a page renamed after it merged needs a redirect even if no deploy shipped it, which is cheap. See notes/documentation-strategy.md.
Uses definition from: DOCBW-03-008
Uses definition from: DOCBW-03-006
DOCBW-03-027 MUST The DOCBW-03-012 step MUST fail when the checked-out commit builds no pages.

With no built page the step checks nothing and would pass. A gate that finds no targets and passes is worse than no gate (DF-09-009).
Extends: DOCBW-03-012
DOCBW-03-013 MUST Each tree-wide pre-commit hook (pass_filenames: false) whose files: matches a docs/ file MUST also run in a workflow whose pull_request trigger fires on that file.

No workflow runs pre-commit, so a hook enforces nothing on a pull request whose author did not run it. A test of the committed tree does not replace the hook when the path filter of its workflow misses the file. Then a pull request that changes only docs/, and breaks the frontmatter of a page or the normative banner, can merge with green checks.
DOCBW-03-014 MUST Each DOCBW-03-013 gate that the review workflow runs MUST run after the shared build step and the built-site checks, on !cancelled(), failing the job without stopping later steps. Nothing swallows its failure (no continue-on-error, no &#124;&#124; true).

The gates check the docs/ sources, not the built site, so they need only the environment the shared build step sets up (DOCBW-06-004); running them first would mean a second install in the same job. A built-site check has no if:, so it is skipped after any earlier failure: placed after those checks, a failed gate cannot hide them, and !cancelled() lets every gate run whatever failed before it, so one push reports every broken gate.
Extends: DOCBW-03-013
DOCBW-03-015 MUST The workflow that runs the DOCBW-03-013 check MUST fire on a pull request that changes .pre-commit-config.yaml or any .github/workflows/*.yml file.

The check reads those files. If it ran only on a pull request that changes Python, the pull request that deletes a gate's step, or adds a docs hook with no step, would merge green and the next unrelated pull request would fail instead.
Extends: DOCBW-03-013

Security Compliance

ID Priority Requirement Related
DOCBW-05-001 MUST All uses: references in docs-build-check.yml MUST be pinned to a specific commit SHA with an inline human-readable version comment, per CISEC-01-001 and CISEC-01-002.

This workflow runs actions from outside the repository. A pin keeps that code fixed to a reviewed commit, as in every other workflow (CISEC-01-001).
Refines: CISEC-01-001
Refines: CISEC-01-002
DOCBW-05-002 MUST The workflow MUST declare permissions: contents: read at the workflow level and no additional permissions, per CISEC-02-002.

The workflow reads the repository, builds the site and checks it. It writes nothing, so it needs no write access. A read-only token limits what a compromised step or action can change (CISEC-02-002).
Refines: CISEC-02-002

Site Publication

Obligations of the publication workflow, .github/workflows/deploy_site.yml, beyond the build and gate obligations DOCBW-03 places on every site-building workflow. Publication runs on a weekday schedule from publish-* tags, gated on main CI, with manual publish and rollback (ADR-0171), and once more when a release is published, dispatched by .github/workflows/publish_after_release.yml. The gate's decisions live in .github/scripts/publish_gate.py.

ID Priority Requirement Related
DOCBW-06-001 MUST The publication workflow MUST be the only workflow that uploads the site to GitHub Pages.

A gate is a property of the paths on which it runs. With one uploader, every requirement placed on the publication workflow binds every path by which the site reaches readers; a second uploader would be a path no DOCBW-06 obligation covers.
DOCBW-06-002 MUST In the publication workflow, the publication gates (DOCBW-03-005, DOCBW-03-007, DOCBW-03-008 and DOCBW-03-012, run through the .github/actions/check-site-publication composite action) MUST run after the site build and before the Pages artifact upload.

After the upload the artifact is already out, so a gate placed later checks a site that has shipped; before the build, site/ does not exist. The ordering is the gate.
Refines: DOCBW-03-006
Uses definition from: DOCBW-03-005
Uses definition from: DOCBW-03-007
Uses definition from: DOCBW-03-008
Uses definition from: DOCBW-03-012
DOCBW-06-003 MUST The publication workflow MUST notify on failure and close the failure notice on a later success, through the notify-failure composite action (CISEC-05-001, CISEC-05-002, CISEC-05-008).

A failed publish leaves the live site stale with no failing pull request to notice it, so the failure has to be reported by the run itself.
Refines: CISEC-05-001
Refines: CISEC-05-002
Refines: CISEC-05-008
DOCBW-06-004 MUST Every workflow that builds the site MUST build it through one shared composite action. That action fixes the checkout (history depth and tags), the dependency set and the mkdocs build command.

A review build is evidence about the published site only when it builds the same thing. Two workflows that each set up their own build can differ in the dependency group, in whether they fetch git tags, and in the build flags. Then a green review does not show that the published site builds. Which commit is built is not part of how it is built, so the action may take the commit as its one input, which a rollback needs (DOCBW-06-020).
DOCBW-06-005 MAY A site-building workflow MAY add steps after the shared build.

The review workflow and the publication workflow need different checks and uploads after the build. Steps after the shared build cannot change the site it built, so both still build the same site.
DOCBW-06-006 MUST NOT A workflow MUST NOT run a mkdocs build of its own.

A second build outside the shared action can differ from it in dependencies, tags or flags. Then the site that one workflow checks is not the site that another publishes.
Extends: DOCBW-06-004
DOCBW-06-007 MUST The publication workflow MUST run on the schedule 7 6 * * 1-5 (06:07 UTC, Monday to Friday) and on workflow_dispatch, and on no other event.

A manual merge to a release branch was skipped for seventeen months, so the site fell 6,966 commits behind main. A weekday schedule keeps the site within a working day of green main with no person in the loop, and a manual run covers an urgent publish or a rollback (ADR-0171).
DOCBW-06-008 MUST NOT A scheduled run, and a manual run from main that does not skip the CI gate, MUST NOT publish while a blocking workflow (DOCBW-06-009) has an open issue carrying both ci:main-failure and that workflow's label.

Push CI on main is path-filtered and cancels superseded runs, so whether every check passed on one commit cannot be read per commit. The open failure issue that notify-failure keeps per workflow says the workflow is red on main, and that state carries over path filters (CISEC-05-011).
Uses definition from: CISEC-05-011
Uses definition from: DOCBW-06-009
DOCBW-06-009 MUST The publication workflow MUST declare its blocking list itself, naming each blocking workflow's file and failure label: Python application, Demo Integration, Spec Check, UI, Lint Markdown and Actions Lint.

These are the workflows whose failure means main is broken. Scheduled bookkeeping workflows, such as ADR Status Drift, report on the project rather than the code, so they do not block. Declared in the workflow, the list is reviewed with the publication it governs.
DOCBW-06-023 MUST NOT The blocking list MUST NOT name the publication workflow.

A failed publish files an issue under the publication workflow's label. If that label blocked, the failure would stop every later publish, including the one that would close the issue.
Extends: DOCBW-06-009
DOCBW-06-010 MUST While a blocking workflow's run on main is unfinished on the candidate commit or one of its ancestors, the CI gate MUST wait up to one hour for it.

An unfinished run can still turn its workflow red, so the gate cannot read the commit's state until it ends. Push CI is path-filtered, so the run that judges the candidate's code can be on an earlier commit: a docs-only tip starts no Python run, while the run for the commit before it may still be going. The hour covers the slowest push workflow; past it the run is treated as red rather than published unchecked. A run of a non-blocking workflow, or on a later commit, cannot change the verdict, so it is not waited for.
DOCBW-06-011 MUST A run that does not publish MUST write its reason to the run summary, naming each blocking issue or unfinished run.

A skip is a green run, so nothing else reports it. The summary is where a maintainer looks to find out why the site did not change.
DOCBW-06-012 MUST NOT A run whose candidate commit is blocked or skipped MUST NOT publish any other commit instead.

An older commit was either published already or skipped for a reason of its own. Falling back would publish a commit nobody chose.
DOCBW-06-013 MUST A scheduled run MUST skip a candidate commit that already has a publish-* tag that is a DOCBW-07-013 publish.

The schedule then never publishes one commit twice, and never undoes a rollback by publishing again the commit it rolled back from. A manual run is a deliberate request, so the rule does not apply to it.
Uses definition from: DOCBW-07-013
DOCBW-06-014 MUST NOT A publish-* tag that is not a DOCBW-07-013 publish MUST NOT trigger the DOCBW-06-013 skip.

The tag ruleset restricts the update and deletion of a publish-* tag, not its creation (#5545), so any account that can push can create one. Without this rule a hand-pushed tag on the tip of main would suppress a publish with no failing check. The tagger is what the tag's author wrote, so the rule guards against an accidental tag, not a deliberate forgery.
Extends: DOCBW-06-013
Uses definition from: DOCBW-07-013
DOCBW-06-015 MUST A run that ignores a publish-* tag under DOCBW-06-014 MUST name the ignored tag in its run summary.

An ignored tag is a sign that someone tagged by hand; naming it lets a maintainer find out why.
Extends: DOCBW-06-014
DOCBW-06-016 MUST Each publish MUST create exactly one annotated tag publish-YYYY-MM-DD.N on the deployed commit, after the deploy succeeds, where the date is the UTC date and N starts at 1 and is always present.

The newest publish-* tag then always names what is live, and a failed deploy leaves no tag for the skip rule to honour. The date is the one on which the gate named the tag (DOCBW-06-031). A push that reports failure but landed, and a re-run of the tag job, find the tag already pushed, so neither makes a second one.
DOCBW-06-017 MUST The DOCBW-06-016 tag's message MUST record the trigger (scheduled, manual, manual with the CI gate skipped, rollback, or release) and the actor.

The tag is the record of the publish. Its message says why a commit went live and who asked, without a search through workflow runs.
Extends: DOCBW-06-016
DOCBW-06-018 MAY A manual run from main MAY skip the CI gate through a boolean skip-ci-gate input that defaults to off.

A workflow can be red for a reason that does not touch the site, such as a flaky demo, and an urgent docs fix cannot wait for it.
DOCBW-06-019 MUST NOT A trigger or input of the publication workflow MUST NOT skip the publication gates of DOCBW-06-002.

The CI gate is about main; the publication gates are about the site that is about to ship. Skipping the first is a judgment about a red workflow, and it says nothing about whether the site is fit to publish.
Extends: DOCBW-06-002
DOCBW-06-020 MUST A manual run from main whose rollback-to input names a publish-* or v* tag MUST redeploy that tag's commit without the CI gate and create a new publish-* tag on it whose message reads "rollback to , by @."

A rollback restores a site that was published before, so the state of today's main is beside the point. The new tag keeps the newest publish-* tag naming what is live. The commit rolled back from keeps its own publish-* tag, so the next scheduled run, which finds that tag on the tip of main, does not publish it again. The run starts from main rather than from the tag, because a manual run executes the workflow file stored at the ref it starts from: a run from a tag would execute that tag's copy, which for every tag made before this design has no gate and no tag step.
DOCBW-06-021 MUST Scheduled, manual, release and rollback runs MUST share one concurrency group that does not cancel a run in progress.

Two publishes at once would race for the tag counter and for Pages, and a cancelled deploy can leave Pages and the tags disagreeing. The group covers the whole run, the gate's wait included: a group on the build, deploy and tag jobs alone would let two runs interleave, so the newest tag could name a deploy that is no longer live. The cost is GitHub's rule of one pending run per group: while a run holds the group, a newer queued run replaces an older queued one, which ends as cancelled with no failure notice, and its starter runs it again. A replaced release run (DOCBW-06-032) has no person to run it again, so a maintainer who sees the released draft still on its placeholder starts a manual publish.
DOCBW-06-022 MUST NOT A step of the publication workflow MUST NOT move or delete a publish-* or v* tag.

A published tag is the record of what was live. The tag ruleset refuses a move or a deletion (#5545), and a repository ruleset cannot grant the GitHub Actions app a bypass, so such a step could only fail.
DOCBW-06-026 MUST NOT A rollback MUST NOT redeploy a commit that is not in main's history.

Anyone who can push can create a publish-* or v* tag (#5545), so a tag is no sign of review. A commit in main's history was merged through review; any other commit was not.
Extends: DOCBW-06-020
DOCBW-06-030 MUST NOT A rollback MUST NOT pass the CI gate when its target commit lacks a local action that the site build loads from that commit.

The build loads setup-python-uv and check-site-publication from the commit it builds, and the releases up to v2024.4.3 predate them. Refused at the gate, such a rollback writes its reason to the run summary (DOCBW-06-011); let through, it would report "Publishing" and then fail in the build.
Extends: DOCBW-06-020
DOCBW-06-024 MUST In the publication workflow, contents: write MUST be held only by the job that pushes the DOCBW-06-016 tag.

That job runs main's tag script and nothing else. Every other job either runs project code or needs no write access (CISEC-02-002).
Refines: CISEC-02-002
Uses definition from: DOCBW-06-016
DOCBW-06-025 MUST When a publish reached Pages but its tag was not pushed, the failure notice MUST say that the newest publish-* tag does not name the live site, and how to recover.

The deploy and the tag cannot succeed or fail together. A deploy left untagged breaks the rule that the newest publish-* tag names what is live. Re-running the tag job repairs it, and finds a tag an earlier attempt pushed instead of adding a second.
Extends: DOCBW-06-016
DOCBW-06-027 MUST NOT The job that builds the site MUST NOT hold a token that can write to the repository or deploy to Pages.

The build runs project code and third-party plugins. A token that can push a tag or deploy, saved by the build's checkout, would let a compromised build step do either (CISEC-02-002).
Extends: DOCBW-06-024
DOCBW-06-028 MUST When a DOCBW-06-010 run is still unfinished after the hour, the CI gate MUST skip the publish.

Past the hour the run is treated as red rather than published unchecked; the next scheduled run tries again.
Extends: DOCBW-06-010
DOCBW-06-029 MUST NOT A manual run of the publication workflow that does not start from main MUST NOT publish.

A manual run executes the copy of the workflow file stored at the ref it starts from. A run started from another ref, a tag included, would execute that ref's copy with the deploy's permissions.
DOCBW-06-031 MUST A run that publishes MUST name its DOCBW-06-016 tag before the site build, pass that name, its date and the newest v* tag on the deployed commit to the build, and create the tag under exactly that name, failing rather than renumbering when the name is taken.

Every page's footer names the publish it belongs to (#5544), and the build prints the footer before the deploy, so the name must be fixed first. A tag renumbered after the deploy would leave every page naming a tag the publish did not make. A taken name is a collision with a hand-made tag, which tags being append-only (DOCBW-06-022) cannot repair, so the tag job fails and its notice says how to recover (DOCBW-06-025). The build job checks, before the upload, that the name is still free and that the footer prints it: a re-run reuses the gate's outputs, and the variables reach the build only through the shared action.
Extends: DOCBW-06-016
DOCBW-06-032 MUST When a GitHub Release is published, the workflow .github/workflows/publish_after_release.yml MUST start a run of the publication workflow from main through workflow_dispatch, naming the release in that run's release input.

A publish that ran before the release was published serves the released draft's placeholder (DOCBW-08-032). Without this run the placeholder stays until the next weekday publish, up to three days (#6393). The release event itself runs from the release's tag, whose copy of the publication workflow is not main's (ADR-0171) and which the github-pages environment does not let deploy, so the release workflow only dispatches. A workflow_dispatch is one of the two events (with repository_dispatch) that a GITHUB_TOKEN can raise to start another workflow.
Depends on: DOCBW-08-028
DOCBW-06-033 MUST A DOCBW-06-032 run MUST apply the CI gate of DOCBW-06-008.

The run publishes main, so main must be green, as it must be for a scheduled publish.
Extends: DOCBW-06-032
Depends on: DOCBW-06-008
DOCBW-06-034 MUST NOT A run whose release input is set MUST NOT publish when its actor is not github-actions[bot], when it also sets rollback-to or skip-ci-gate, or when the input names no published GitHub Release. The gate fails such a run and writes its reason to the run summary.

The input only labels the run, but the label goes into the tag message (DOCBW-06-017), so a person who set it by hand would make a false record of why a commit went live. GitHub cannot hide an input from the manual-run form, so the gate enforces who sets it. A refusal fails visibly rather than publishing as a manual run, which would hide the misuse.
Extends: DOCBW-06-032
DOCBW-06-035 MUST NOT A DOCBW-06-032 run MUST NOT apply the skip rule of DOCBW-06-013.

The release is often published on a day whose scheduled publish already took main's tip, so the skip rule would skip the one run that serves the frozen draft.
Extends: DOCBW-06-032
See also: DOCBW-06-013 — the skip rule a release run is exempt from

Release Promotion and Site Staleness

Obligations of the workflows that read the publish-* tags DOCBW-06 makes: the promote workflow .github/workflows/promote_release.yml, which turns a publish into a release (ADR-0006, ADR-0171); the release tag check .github/workflows/release_tag_check.yml; and the staleness alarm .github/workflows/site_staleness.yml. Their logic lives in .github/scripts/release.py, and every tag query in .github/scripts/release_tags.py.

ID Priority Requirement Related
DOCBW-07-001 MUST The promote workflow MUST create the next vYYYY.M.P tag (ADR-0006) as an annotated tag on the commit of the chosen publish-* tag, and open a draft GitHub Release for it whose notes are generated since the previous v* tag.

A release then names a snapshot that passed CI and the site checks and was live, with no SHAs matched by eye. The release dialog cannot target an existing tag, and its default target is main, which is not what the site shows. A draft lets the maintainer write the notes in the usual editor before anyone sees the release.
DOCBW-07-011 MUST The year and month of a DOCBW-07-001 release tag MUST be those of the UTC promotion date, with P 0 for the month's first release and one more than the month's highest otherwise.

The release names when it shipped, not when the snapshot was first published, and ADR-0006 counts P within the month.
Extends: DOCBW-07-001
DOCBW-07-012 MUST A promote run with an empty input MUST promote the newest DOCBW-07-013 publish, unless DOCBW-08-042 names the publish that froze a draft.

The newest publish names what the site shows now, which is what a maintainer most often means to release. A release that freezes a draft is the exception: its draft keeps the date of the publish that froze it, so that publish is promoted even after later ones.
Extends: DOCBW-07-001
Uses definition from: DOCBW-07-013
DOCBW-07-002 MUST NOT The promote workflow MUST NOT create a v* tag when its input is not an existing publish-* tag that is a DOCBW-07-013 publish.

A tag the workflow's GITHUB_TOKEN pushes starts no other workflow, so the release tag check never sees it and the workflow must check its own input. Anyone who can push can create a publish-* tag (#5545), so a name alone is no sign that the commit was published.
Extends: DOCBW-07-001
Uses definition from: DOCBW-07-013
DOCBW-07-003 MUST NOT The promote workflow MUST NOT create a v* tag that does not compare strictly greater than every existing version-shaped v* tag.

ADR-0006 requires release tags to increase monotonically. A tag from a later month pushed by hand would otherwise make the next promotion name a release older than the latest one.
Extends: DOCBW-07-001
DOCBW-07-004 MUST NOT A run of the promote workflow that does not start from main MUST NOT create a tag or a release.

A manual run executes the copy of the workflow file stored at the ref it starts from. A run from another ref would execute that ref's copy with write access to the repository.
Extends: DOCBW-07-001
DOCBW-07-005 MUST The promote workflow MUST trigger on workflow_dispatch only, with contents: read at the workflow level and contents: write only on the job that pushes the release tag and creates the release.

Promotion is a maintainer's decision, so nothing starts it on its own. The one job that writes needs to push a tag and create a release, and nothing more (CISEC-02-002).
Refines: CISEC-02-002
DOCBW-07-006 MUST The publish gate, the promote workflow, the release tag check and the staleness alarm MUST read the local clone's publish-* and v* tags, the commit, object id and message of a tag, and the bot's tagging identity only through the shared helper .github/scripts/release_tags.py.

One helper gives all four the same answer to "which commits were published." A hand-pushed tag, which the scheduled skip ignores, must not pass as a publish to promote, to the release check or to the staleness alarm either.
DOCBW-07-013 MUST The DOCBW-07-006 helper MUST count as a publish only an annotated publish-YYYY-MM-DD.N tag whose tagger is github-actions[bot].

The tag ruleset does not restrict who creates a publish-* tag, so a hand-pushed or lightweight tag must not pass as a publish to the skip, to promote, to the release check or to the staleness alarm. A name the publish workflow never makes is no publish, whoever tagged it.
Extends: DOCBW-07-006
DOCBW-07-007 MUST A push of a v* tag whose commit has no DOCBW-07-013 publish MUST file or update a failure issue through the notify-failure composite action.

A release cut by hand can name a commit that never passed the site checks or was never live. Tags are append-only (#5545), so the check can only report it for a maintainer to review.
Uses definition from: CISEC-05-008
Uses definition from: DOCBW-07-013
DOCBW-07-014 MUST NOT The release tag check MUST NOT block a v* tag push.

The check runs after the tag exists and only reports; a maintainer decides what to do about a release that names no publish.
Extends: DOCBW-07-007
DOCBW-07-008 MUST When the newest DOCBW-07-013 publish is more than 4 weekdays older than the newest commit on main, and main has commits that are not in the published commit's history, the staleness alarm MUST keep one failure issue open through the notify-failure composite action.

A skipped publish is a green run, so nothing else reports a site that stopped moving: the site once fell 6,966 commits behind main unseen (ADR-0171). Weekdays, not days, are counted, so a weekend alone never triggers it. The alarm also checks after every run of the publish workflow, so the next publish closes it.
Uses definition from: DOCBW-07-013
DOCBW-07-015 MUST The first staleness check after a publish that ends the DOCBW-07-008 condition MUST close the issue.

The alarm checks after every run of the publish workflow, so the next publish closes it without waiting for the schedule.
Extends: DOCBW-07-008
DOCBW-07-009 MUST NOT A step of the promote workflow, the release tag check or the staleness alarm MUST NOT move or delete a publish-* or v* tag.

The tag ruleset refuses a move or a deletion (#5545), and a repository ruleset cannot grant the GitHub Actions app a bypass, so such a step could only fail.
Extends: DOCBW-06-022
DOCBW-07-010 MUST When the chosen publish's commit already carries the latest v* tag, made by the promote workflow, and that tag has no GitHub Release, the promote workflow MUST open the draft release for that tag instead of creating another tag.

A run whose release step failed leaves its tag pushed. Re-running it then finishes the release instead of tagging one commit twice.
Supersedes: DOCBW-07-001
Supersedes: DOCBW-07-016
DOCBW-07-016 MUST When the chosen publish's commit carries a v* tag in any case other than DOCBW-07-010 and DOCBW-08-025, the promote workflow MUST refuse the run.

A commit already released, a commit whose release a later one superseded, and a commit tagged by hand each need a maintainer's decision, not a second tag or a draft for a tag nobody promoted.

Frozen Protocol Specification Drafts

Obligations that keep each released draft of the Protocol Specification readable, unchanged, at spec/draft-N/ beside the current draft (ADR-0188): the drafts register that states each draft once, the archive that the promote workflow .github/workflows/promote_release.yml attaches to a release that carries a draft, and the step by which the publication workflow and the review workflow serve the released drafts from those archives. Immutable releases are enabled on the repository, so a published release's assets never change, and an asset can be attached only while the release is a draft. The promote builds and checks the archive before any draft release exists, and creates the draft release with its assets attached, so every draft release a maintainer can publish already carries them. A release is published when GitHub reports a release for its tag that is not a draft. A release carries a matching DOCBW-08-009 pair when both files are attached to it and every file of the attached archive, and no other file, has the digest that the attached manifest lists.

ID Priority Requirement Related
DOCBW-08-001 MUST Each draft of the Protocol Specification MUST have exactly one entry in the drafts register docs/reference/vultron-spec/drafts.yaml. The entry gives the draft's version draft-N, its status (unreleased or released) and its date in the YYYY-MM-DD format. An unreleased entry's date is the day the entry was added to the register. A released entry's date is the date of the publish that froze the draft: the publish that the promote workflow made the draft's release from. A released entry also gives the v* tag of the release that carries the draft.

The promote workflow, the deploy and the pages must agree on which drafts are released and by which release. Facts that are written in one place cannot disagree. A frozen draft's pages are the pages of the publish that froze it, so that publish's date is the date the draft keeps. draft-1, released before this rule, keeps the date its entry was added, since a released entry never changes (DOCBW-08-003).
DOCBW-08-002 MUST The drafts register loader MUST refuse a malformed register and name the failing entry by path:line:col. These are malformed: a duplicate version, a version that is not draft-N, a gap in the draft numbers, a released entry with no tag, an unreleased entry with a tag, more than one unreleased entry, an unreleased entry that is not the highest-numbered, and two released entries that name the same tag.

A wrong entry would make the promote attach the wrong draft or the deploy serve none. A refusal that names the line lets the author fix it at once.
Extends: DOCBW-08-001
DOCBW-08-003 MUST A step of .github/workflows/docs-build-check.yml MUST fail when the drafts register at the checked-out commit and the register at a v* tag disagree on a draft released by that tag: the tag's register names such a draft and the checked-out register lacks that entry or holds a different one, or the checked-out register names an existing tag as a draft's release and that tag's register lacks the same entry.

The entry is marked released before the promote, so the release tag carries the entry that names it. After that release, the draft names one text, and a changed or removed entry would make the site serve or describe a different one. The shared build fetches every tag, so the step can read the register at each one.
Extends: DOCBW-08-001
DOCBW-08-004 MUST The status box of the Protocol Specification and the status tables of its revision log MUST be committed fragments generated from the drafts register.

Today the status of a draft is written by hand in two places. A generated status cannot disagree with the register that the release automation reads, and a committed fragment shows each change in the pull request that makes it.
Uses definition from: DOCBW-08-001
DOCBW-08-005 MUST A pre-commit hook MUST fail when a committed DOCBW-08-004 fragment differs from a fresh generation from the drafts register.

Without the check, a register edit that is not regenerated leaves the pages saying one thing while the automation reads another. DOCBW-03-013 then runs the hook in the review workflow too.
Extends: DOCBW-08-004
DOCBW-08-006 MUST When the drafts register holds an unreleased entry, the generated status box MUST label the Protocol Specification "Current draft (work in progress)".

A reader must be able to tell the moving current text from a frozen draft, which the banner of a frozen page names.
Extends: DOCBW-08-004
DOCBW-08-040 MUST While the drafts register holds an unreleased entry, the status box and that entry's revision log status table MUST show, as the current draft's last-updated date, the date of the publish that built the page, which the site build reads from the DOCBW-06-031 inputs.

The current draft changes with each publish, so a date fixed in the register cannot say which text a reader sees. The publish date can, and a reader cites it with the publish tag in the page footer.
Extends: DOCBW-08-004
Uses definition from: DOCBW-06-031
DOCBW-08-044 MUST A site build that no publish makes, such as a pull request's review build or mkdocs serve, MUST show "unpublished build" where DOCBW-08-040 shows the publish date.

A review build has no publish, so a date there would name a text no publish served. Saying so keeps the slot from ever showing a wrong date.
Extends: DOCBW-08-040
DOCBW-08-007 MUST When the drafts register holds no unreleased entry, the generated status box MUST name the newest released draft and its release tag, and carry no current-draft label.

The promoted commit holds the register with the draft just marked released and no newer draft opened, so its pages are the text the release carries. The archive is built from those pages, so they must read as that released draft, not as a draft still in progress.
Extends: DOCBW-08-004
DOCBW-08-008 MUST The generated revision log status tables MUST link the frozen copy at spec/draft-N/ of every released draft.

A reader who finds a draft in the revision log needs its permanent address. A generated link cannot miss a released draft.
Extends: DOCBW-08-004
DOCBW-08-009 MUST When the drafts register at the chosen publish's commit names the run's release as the release of draft-N, the promote workflow MUST create that draft release with the archive vultron-spec-draft-N.tar.gz and its manifest vultron-spec-draft-N.sha256 attached, in the step that creates it.

A published release is immutable, and the maintainer publishes the draft by hand after reviewing its notes. A draft release that existed without its assets could be published in that state, and could then never get them. The promote is the one step that knows both the release and its commit, so the frozen copy needs no manual step.
Extends: DOCBW-07-001
Uses definition from: DOCBW-08-001
DOCBW-08-010 MUST NOT A promote run whose release the drafts register names for no draft MUST NOT attach an archive or a manifest.

A monthly release that carries no new draft would otherwise claim a frozen copy of a text that it does not release.
Extends: DOCBW-08-009
DOCBW-08-011 MUST The promote workflow MUST refuse the run, and create no tag, when the drafts register at the chosen publish's commit names as a draft's release a tag that is not the run's release and whose own register does not hold the same entry. Such a tag either does not exist or is an earlier release that never carried the draft.

The register is edited before the promote and predicts the tag name. When the prediction is wrong, for example because the promote moved to the next month, or names an earlier release, the release would carry pages that name a different release, and no frozen copy would ever be made; once that other release is published, every deploy fails (DOCBW-08-033).
Extends: DOCBW-08-009
DOCBW-08-041 MUST The promote workflow MUST refuse the run, and create no tag, when the drafts register at the chosen publish's commit names the run's release for a draft whose date is not the chosen publish's date. The refusal names both dates and says how to date the entry again.

The date of a released entry is the date of the publish that froze the draft (DOCBW-08-001). The entry is written before that publish runs, so it holds a prediction. When the publish of that date never ran, or the maintainer names a different one, the draft would keep a date that no publish of it has.
Extends: DOCBW-08-009
Uses definition from: DOCBW-08-001
DOCBW-08-042 MUST When the promote workflow's input is empty and the drafts register at the newest publish's commit holds no unreleased entry, its newest released entry's date is not that publish's date, and no published GitHub Release of that entry's release tag exists, the run MUST promote the newest publish of that date whose register holds the same entry, when one exists. The run chooses that publish before it names its release.

A maintainer may run the promote days after the publish that froze the draft, once later publishes exist. Promoting the publish of the draft's date makes that run succeed without naming a tag, and its pages are the frozen text: the commits after it hold the same entry, and every change to the text goes into the next draft. Choosing it before naming the release lets a run after one that tagged that publish's commit and failed resume that release (DOCBW-07-012). Once that release is published the draft is done, and until the next draft is opened a later release carries no draft and promotes the newest publish, as DOCBW-07-012 says.
Refines: DOCBW-07-012
Uses definition from: DOCBW-08-001
DOCBW-08-043 MUST The command drafts-register release MUST mark the unreleased entry of the drafts register released, with the next v* release tag and the date of the next scheduled publish (DOCBW-06-007), and write the DOCBW-08-004 fragments from the result. A --release and --date pair names the tag and the date instead.

The maintainer must not predict the release tag and the publish date by hand: a wrong prediction makes the promote refuse (DOCBW-08-011, DOCBW-08-041). The publish after the change merges is the next scheduled one, which is the publish that freezes the draft. When that publish does not run, the command dates the entry again.
Uses definition from: DOCBW-08-001
Uses definition from: DOCBW-06-007
Uses definition from: DOCBW-08-004
DOCBW-08-045 MUST When the drafts register holds no unreleased entry, the DOCBW-08-043 command MUST date again the newest released entry if its release tag does not exist yet, and refuse otherwise, writing nothing.

An entry whose release has not been made can still change: when the publish it was dated for does not run, running the command again dates it for the next one (DOCBW-08-041). An entry whose release exists never changes (DOCBW-08-003), and the command fetches the tags first so a stale clone cannot mistake one for the other.
Extends: DOCBW-08-043
Uses definition from: DOCBW-08-003
DOCBW-08-012 MUST The promote workflow MUST refuse the run, and create no tag, when the drafts register at the chosen publish's commit names the run's release for a draft and also holds an unreleased entry.

An unreleased entry means a newer draft is open at that commit, so its pages are not the text of the draft the release would carry, and the frozen copy would freeze the wrong text.
Extends: DOCBW-08-009
DOCBW-08-013 MUST The DOCBW-08-009 archive MUST hold the pages that the shared site build (DOCBW-06-004) renders from docs/reference/vultron-spec/ at the release's commit, with every file those pages load. Its root is the specification's root: the page built at reference/vultron-spec/index.html is index.html in the archive.

The frozen copy must be the text the release carries, rendered by the toolchain of that release, and served at spec/draft-N/ with the same page paths as the live specification has below its own root.
Uses definition from: DOCBW-06-004
Uses definition from: DOCBW-08-009
DOCBW-08-014 MUST The site build of the DOCBW-08-009 archive MUST pass the chosen publish tag and its date, and the run's release tag, as the build inputs of DOCBW-06-031.

Every page's footer prints those inputs. A frozen page whose footer named no release, or another publish, would contradict its banner.
Uses definition from: DOCBW-08-009
Uses definition from: DOCBW-06-031
DOCBW-08-015 MUST Every relative reference in a page of the DOCBW-08-009 archive MUST resolve to a file inside the archive.

A reference that resolves into the live site would let a later change of the live site alter the frozen page, and would break the archive when it is read offline.
Uses definition from: DOCBW-08-009
DOCBW-08-016 MUST Every link in a page of the DOCBW-08-009 archive to a page outside the Protocol Specification MUST be an absolute URL below the site's site_url.

The frozen copy freezes the specification, not the rest of the site. A relative link out of the specification would resolve to nothing in the archive, or to an unrelated page below spec/.
Uses definition from: DOCBW-08-009
DOCBW-08-017 MUST Every page of the DOCBW-08-009 archive MUST carry a banner. The banner names the draft version, the release tag, the full commit SHA and the UTC build date. It also says that the page's links outside the specification go to the live site, which changes.

A reader who opens a frozen page must see which text it is and how to cite it, and must not take a linked page of the live site for part of the frozen text.
Uses definition from: DOCBW-08-009
DOCBW-08-018 MUST The DOCBW-08-009 manifest MUST list every file of the archive, and no other file, with its SHA-256 digest, in the line format that sha256sum --check reads.

The deploy checks each unpacked file against the manifest. A standard format also lets a reviewer check a downloaded archive with no project tool.
Uses definition from: DOCBW-08-009
DOCBW-08-019 MUST NOT The job of the promote workflow that builds the DOCBW-08-009 archive MUST NOT hold a token that can write to the repository.

The build runs project code from the promoted commit. Only the job that pushes the release tag and attaches the assets needs write access, as the publication workflow already separates build and tag.
Extends: DOCBW-07-005
Uses definition from: DOCBW-08-009
DOCBW-08-020 MUST NOT The job of the promote workflow that attaches the DOCBW-08-009 assets MUST NOT run code from the promoted commit. It takes the archive and the manifest as an artifact of the DOCBW-08-019 job.

The job holds write access. Code from the promoted commit is not the reviewed copy on main that the run started from, so running it with write access would undo the split of DOCBW-08-019.
Extends: DOCBW-08-019
Uses definition from: DOCBW-08-009
DOCBW-08-021 MUST Before it pushes the release tag or creates the release, the promote workflow MUST unpack the built DOCBW-08-009 archive into an empty folder and fail the run when that tree breaks DOCBW-08-015 or does not match the manifest.

Tests cover the archive builder on fixtures, not the real archive. A defect found before anything exists leaves nothing behind, and a defect found after publication can never be fixed.
Uses definition from: DOCBW-08-009
Uses definition from: DOCBW-08-015
DOCBW-08-022 MUST After it creates the DOCBW-08-009 draft release, the promote workflow MUST check that the attached assets are byte-identical to the built ones.

The maintainer publishes a draft release once its run is green, and a published asset can never be replaced, so a truncated upload must fail the run while the release is still a draft.
Uses definition from: DOCBW-08-009
DOCBW-08-023 MUST When the upload of a DOCBW-08-009 asset, the DOCBW-08-022 check, or any later step of the run fails, the promote workflow MUST delete the draft release it created before the run ends.

A draft release left without its matching assets could be published by hand and then never repaired, and the maintainer publishes only the draft release of a green run, so a red run leaves none. A draft release is not yet immutable, so deleting it is safe, and the tag stays: DOCBW-07-009 forbids deleting it, and a re-run then resumes it under DOCBW-07-010.
Extends: DOCBW-08-022
Uses definition from: DOCBW-08-009
DOCBW-08-037 MUST When the DOCBW-08-023 delete fails, the promote workflow MUST fail the run with a message that names the draft release and says that it is incomplete and must not be published.

A draft release the run could not delete may lack its matching pair. The maintainer must learn not to publish it; the next run deletes it under DOCBW-08-025.
Extends: DOCBW-08-023
DOCBW-08-024 MUST When the drafts register names the run's release as a draft's release and that release is a draft with a matching DOCBW-08-009 pair, the refusal of DOCBW-07-016 MUST say that the draft release is complete and waiting for the maintainer to publish it.

A re-run after a green run has nothing to do. The message tells the maintainer to publish rather than to look for a failure.
Extends: DOCBW-07-016
Uses definition from: DOCBW-08-009
DOCBW-08-025 MUST When the chosen publish's commit carries the latest v* tag, made by the promote workflow, whose release is a draft that the drafts register names as a draft's release and that lacks a matching DOCBW-08-009 pair, the promote workflow MUST delete that draft release and continue as DOCBW-07-010 states.

A run stopped from outside, for example by a cancelled runner, can leave a draft release before DOCBW-08-023 deletes it. The re-run removes it, so the draft release a maintainer sees again carries its assets, and no path ever completes the assets of an existing draft.
Supersedes: DOCBW-07-016
Uses definition from: DOCBW-08-009
See also: DOCBW-07-010 — the resume of a tag with no release that the run continues as
DOCBW-08-026 MUST When the drafts register names the run's release as a draft's release and that release is published without a matching DOCBW-08-009 pair, the refusal of DOCBW-07-016 MUST say that the published release cannot take the archive.

The ordering of DOCBW-08-021 to DOCBW-08-025 prevents this case, but a maintainer can still publish a draft release that a stopped run had not yet deleted. An immutable release refuses a new asset, so the maintainer must learn that a re-run cannot help. The rule is limited to the run's own release, so an older release never blocks the promote of a newer one.
Extends: DOCBW-07-016
Uses definition from: DOCBW-08-009
DOCBW-08-027 MUST The publication workflow MUST read the drafts register as main holds it when the run starts, whatever commit the run deploys.

A rollback deploys an older commit, whose register may not name a draft that was released later. Reading the register from main keeps every frozen draft served across any rollback the gate accepts (DOCBW-08-038).
Uses definition from: DOCBW-08-001
DOCBW-08-038 MUST NOT A rollback MUST NOT pass the CI gate when its target commit lacks the DOCBW-08-028 step.

The build runs the target commit's own steps and checks, so a target older than the step would serve no frozen draft, and its publication checks, which lack the DOCBW-08-036 exemption, would judge the frozen pages. Refused at the gate, the rollback writes its reason to the run summary (DOCBW-06-011), as DOCBW-06-030 does for a missing local action. Every rollback the gate accepts serves every frozen draft (DOCBW-08-027).
Extends: DOCBW-06-030
Uses definition from: DOCBW-08-028
DOCBW-08-028 MUST For each released draft whose release is published, the publication workflow MUST unpack the release's DOCBW-08-009 archive into site/spec/draft-N/ in the job that builds the site, after the shared build and before the publication gates of DOCBW-06-002.

A Pages deploy replaces the whole site, so every deploy must place every frozen draft again. Unpacking before the gates lets the link check cover the frozen pages, and the build job holds no token that can write or deploy (DOCBW-06-027).
Uses definition from: DOCBW-08-009
Uses definition from: DOCBW-06-002
DOCBW-08-029 MUST The DOCBW-08-028 step MUST refuse an archive, before it writes any file, when a member has an absolute path, a .. component, or a type other than a regular file or a folder.

The manifest is checked after the unpack, so a crafted member could otherwise write outside site/spec/draft-N/, or plant a link, before any check sees it.
Extends: DOCBW-08-028
DOCBW-08-030 MUST The DOCBW-08-028 step MUST fail unless the unpacked tree holds exactly the files that the manifest lists, each with the listed SHA-256 digest.

The frozen copy is the bytes the promote built. A missing, extra or changed file means the site would serve a text that no release carries.
Extends: DOCBW-08-028
DOCBW-08-031 MUST NOT A workflow that builds the site MUST NOT render any page from a commit other than the one it checked out. A frozen draft's pages come only from its DOCBW-08-009 archive.

A rebuild of an old draft runs today's environment on an old tag, so its output can drift. A frozen draft comes only from its archive.
Uses definition from: DOCBW-08-009
DOCBW-08-032 MUST For each released draft whose release is not published, the DOCBW-08-028 step MUST write a placeholder page at site/spec/draft-N/index.html that names the release, and name the draft in the run summary.

The register marks a draft released before its tag exists, and its release stays a draft until the maintainer publishes it. The pages link the frozen copy from then on. The placeholder keeps that link from being dead in every build in between, so the publish the promote needs is not blocked, and the summary shows why the frozen copy is not served yet. A token with read access cannot see a draft release, so a draft counts as not published.
Extends: DOCBW-08-028
DOCBW-08-033 MUST When a published release that the drafts register names as a draft's release lacks a DOCBW-08-009 file, or its archive fails DOCBW-08-030, the DOCBW-08-028 step MUST fail, naming the draft and the release.

A deploy that went on without the draft would drop a frozen draft from the site with no failing check. The step runs before the Pages upload, and in the review workflow too (DOCBW-08-035), so a pull request sees the failure the deploy would. The failure notice of DOCBW-06-003 then reports a failed deploy.
Extends: DOCBW-08-028
Uses definition from: DOCBW-08-009
Uses definition from: DOCBW-08-030
DOCBW-08-034 MUST The DOCBW-08-028 step MUST fail when the shared site build produced any file below site/spec/.

spec/ is reserved for frozen drafts. A page built there would be overwritten by an archive, or would sit at an address that a later draft claims.
Extends: DOCBW-08-028
DOCBW-08-035 MUST The review workflow .github/workflows/docs-build-check.yml MUST run the DOCBW-08-028 step before its publication checks, reading the drafts register at the commit it checked out.

The live pages link every frozen draft. The pull-request check must see the same tree as the deploy, or its link check fails on those links, or misses a broken one. A pull request that edits the register is checked with its own edit.
Extends: DOCBW-08-028
DOCBW-08-039 MUST The job of the promote workflow that builds the DOCBW-08-009 archive MUST run the DOCBW-08-028 step after the shared build and before its publication checks, reading the drafts register at the promoted commit.

The Revision Log at that commit links the frozen copy of every released draft, including the draft this run releases. Without the served tree, the link check and the archive build find no file for those links and fail, so the run makes no tag. With it, the archive builder writes each link as its live URL (DOCBW-08-016).
Extends: DOCBW-08-028
Uses definition from: DOCBW-08-009
DOCBW-08-036 MUST NOT The DOCBW-03-008 continuity step, the DOCBW-03-012 step and the DF-11-045 reading-path box check MUST NOT judge files below site/spec/, and no URL below spec/ is added to the DOCBW-03-008 record of served URLs.

A frozen page never changes, so a rule added after its release would fail it on every later build. The register and DOCBW-08-033 keep each frozen draft served, and the link check still covers its pages.
Supersedes: DOCBW-03-008
Supersedes: DOCBW-03-012
Supersedes: DF-11-045
Uses definition from: DOCBW-08-028

Duration

Requirements for a canonical representation of time durations independent of start/end timestamps. Applicable wherever a duration must be exchanged in JSON, such as embargo policy records and embargo initialization at case creation.

File ID: DUR

Python / Pydantic v2 Mapping

ID Priority Requirement Related
DUR-05-001 SHOULD Duration fields SHOULD use datetime.timedelta as the internal Python representation

timedelta is the standard library type for elapsed time, so end = start + duration (DUR-06-002) and range checks such as EP-03-002 work directly on it. Code that kept the string form would have to parse it at every comparison and could parse it differently in different places.
DUR-05-002 MUST This codebase MUST serialize each duration field to an ISO 8601 duration string at the JSON wire layer, never to a plain number.

Pydantic can be configured to serialize a timedelta as a number of seconds, which would put a unitless value on the wire and break DUR-01-002. Fixing the wire form to the ISO 8601 string keeps the internal type a private choice that other implementations never see.

Embargo Duration Semantics

ID Priority Requirement Related
DUR-07-005 MUST This codebase MUST log at INFO level each application of a default embargo duration at case creation (DUR-07-003).

How this codebase makes the creation-time default visible to an operator; split from DUR-07-003 so that item states only the EM state other participants observe (MS-12-010). No other participant reads the log.
See also: DUR-07-003 — names the event; logging it does not state how the ACTIVE state is reached

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

Receive EP (Embargo Proposed)

Behaviors triggered when a participant receives an EP (Embargo Proposed) message, transitioning EM state to Proposed and acknowledging receipt. Written in the voice of the formal protocol, in which every Participant is a peer. In the CASE_MANAGER topology (PCR-08-001) a participant addresses its proposal to the CASE_MANAGER alone, so the Participant receiving EP is the CASE_MANAGER on receipt; every other participant reaches the same EM state through ledger replay, and is asked for its answer by the Invite the CASE_MANAGER relays to it. "Emit EK" is discharged by the CASE_MANAGER's commit and announcement of the received activity; no EK message exists (EP-09-009). See EP-09 and ADR-0113 as amended.

Trigger: Message Received — EP

ID Priority Requirement Related
EMB-01-006 MUST This codebase MUST seal the Reject of the Invite that EMB-01-002 requires before it queues it (ID-04-005).

A redelivery reads the sealed record as "already answered", so the refusal is sent once however often the Invite arrives (HP-01-014).
Extends: EMB-01-002
See also: ID-04-005 — context for the reader
EMB-01-007 MUST This codebase MUST queue again, under its own id, a sealed Reject of EMB-01-002 that the outbox no longer holds (ID-04-005).

The seal of EMB-01-006 makes a redelivery read the Invite as answered. Without the requeue, a failed queue write would leave the proposal unanswered for good, and the proposer would wait for a Reject that never comes.
Extends: EMB-01-006
See also: EMB-01-002 — reached through the link to EMB-01-006
See also: ID-04-005 — context for the reader

Actor-Voluntary Embargo Termination (Trigger Side)

Trigger-side factory for voluntarily ending an active embargo (e.g., fix deployed or ready). "The actor" here is the actor enacting the CASE_MANAGER role: the factory's canonical case-state write (EM → EXITED, ledger commit, teardown announce) is gated on CVDRole.CASE_MANAGER (terminate_embargo_bt runs ResolveCaseManagerNode before the state mutation) and is authorised by the Case Owner by default (CM-02-005). A teardown that a received P, X or A report calls for is authorised by the Case Owner's adoption of that value, with no second gate (RSH-07-001, ADR-0210). A non-manager Participant that wishes to end an embargo does not run this trigger to write canonical state; it initiates termination by reporting the condition or notifying intent (VP-11-003, VP-13-017/018), and terminates only its own compliance. See CONCERN-3280 for the reconciliation of the participant-facing protocol prose with this authority model.

Trigger: State Entered — EM.ACTIVE

ID Priority Requirement Related
EMB-14-004 MUST The create_terminate_active_embargo_tree factory MUST require the actor to supply a termination reason (EMB-14-001) before delegating to terminate_embargo_bt.

A tree that reached terminate_embargo_bt with no reason would end the embargo with nothing to audit, which EMB-14-005 forbids.
Implements: EMB-14-001
EMB-14-007 MUST The create_terminate_active_embargo_tree factory MUST have the actor choose the reason through the matching Evaluator call-out point: ExitEmbargoWhenDeployed, ExitEmbargoWhenFixReady or ExitEmbargoForOtherReason. EmbargoExitPolicyGuard or EmbargoExitOverride (EMB-14-002, EMB-14-003) follows, then the OnEmbargoExit actuator.

A Selector of Evaluator call-out points gives actors a clear interface with three choices, and it lets a deployment inject a policy-rule backend (ADR-0025). Each deployment can then supply the termination reason in its own way with no change to the tree.
Extends: EMB-14-004
See also: EMB-14-003 — context for the reader
EMB-14-002 MUST The create_terminate_active_embargo_tree factory MUST include an EmbargoExitPolicyGuard Evaluator call-out point that runs after the reason Selector and before OnEmbargoExit.

Separating the reason selection (actor intent) from the policy check (system authorization) allows external policy engines to block termination on grounds orthogonal to the stated reason (e.g., active revision negotiation, pending approvals) without coupling the guard logic to the reason semantics.

ECA Details

Preconditions

- EM state is Active or Revise; reason Selector has succeeded
- EM state: ACTIVE, REVISE

Steps

1. [system] Run EmbargoExitPolicyGuard call-out point → Returns SUCCESS (policy permits) or FAILURE (policy vetoes)

Postconditions

- SUCCESS: pipeline continues to OnEmbargoExit and terminate_embargo_bt. FAILURE: termination blocked; actor may retry with override.

Extends: EMB-14-007
EMB-14-008 MAY EmbargoExitPolicyGuard (EMB-14-002) MAY veto termination whatever reason the actor chose.

A policy engine can block termination on grounds orthogonal to the stated reason, such as an active revision negotiation or a pending approval.
Uses definition from: EMB-14-002
EMB-14-003 SHOULD The create_terminate_active_embargo_tree factory SHOULD include an EmbargoExitOverride Evaluator call-out point in a Selector alongside EmbargoExitPolicyGuard.

Providing an override seam lets actors exercise their authority to exit in exceptional circumstances without requiring code changes. The override is a distinct call-out point so that integrators can log, gate, or audit it separately from the normal policy path.

ECA Details

Preconditions

- EM state is Active or Revise; reason Selector succeeded; EmbargoExitPolicyGuard returned FAILURE
- EM state: ACTIVE, REVISE

Steps

1. [actor] Invoke EmbargoExitOverride call-out point → Override accepted; pipeline continues to OnEmbargoExit

Postconditions

- Override recorded; termination proceeds; audit trail reflects override

Extends: EMB-14-002 — Override is the fallback arm of the policy authorization Selector
EMB-14-009 SHOULD When the actor explicitly accepts responsibility for overriding policy, EmbargoExitOverride (EMB-14-003) SHOULD return SUCCESS, so that termination proceeds despite a policy veto.

The override exists so that an actor can exit in exceptional circumstances. It does so only when the actor takes responsibility for overriding the policy.
Extends: EMB-14-003

Inbound Embargo-Response Decision (Received Side)

Behaviors triggered when an actor receives an inbound embargo overture and must decide how to respond. Two overture flows are distinguished: (Flow A) an EM-level embargo proposal (EP) proposing terms, whose acceptance moves the shared EM state; and (Flow B) a PEC-level invitation (Invite(EmbargoEvent)[target=Actor, context=VulnerabilityCase]) asking the actor to become a signatory to an embargo, whose acceptance advances that participant's Participant Embargo Consent (PEC) state. The pre-PEC simulator conflated these into a single _ChooseEmProposedResponse fallback; the production protocol separates the shared EM lifecycle (EMB-01..EMB-09) from per-participant consent (CM-18, ADR-0048). This group specifies a single decision seam layered over both flows: it selects the response (accept / reject / counter) while delegating the mechanical transition to the existing received and trigger BTs. The mechanics already exist (invite/accept/reject trees, propose/accept/reject trigger use cases); the decision layer chooses among them with a default-accept policy, decided by the deciding actor's own policy and approved by no other actor.

Trigger: Message Received — EP | InviteToEmbargoOnCase

ID Priority Requirement Related
EMB-15-001 MUST The inbound embargo-response decision seam MUST default to accepting a well-formed embargo overture (Flow A: EP proposing terms; Flow B: InviteToEmbargoOnCase).

The recommended CVD behavior is to accept an offered embargo and negotiate revisions separately rather than block coordination. A deterministic accept-by-default keeps actors runnable without a human in the loop, and the DETERMINISTIC call-out bundle (BT-23) supplies the default. Structuring acceptance as an Evaluator call-out point lets the deciding actor's own UI or agent policy decide later without changing the tree.

ECA Details

Preconditions

- Inbound EP or InviteToEmbargoOnCase received; case is embargo-eligible (CS not public/exploit/attacks per EMB-01-002); no external adjudication backend injected (deterministic default in force).

Steps

1. [system] Run EvaluateEmbargoProposal Evaluator call-out point → Returns SUCCESS (default-accept) under the DETERMINISTIC bundle
2. [system] Delegate to the flow-appropriate acceptance BT → Flow A activates/records via accept_embargo_trigger_bt; Flow B marks the consent row AGREED via accept_invite_to_embargo_tree

Postconditions

- Overture accepted by default; EM (Flow A) or PEC (Flow B) advanced by the existing mechanism

EMB-15-005 MUST When no external adjudication backend is injected, the EvaluateEmbargoProposal Evaluator call-out point MUST return SUCCESS so the actor accepts by default, delegating to the existing acceptance mechanism (accept_embargo_trigger_bt for Flow A; accept_invite_to_embargo_tree for Flow B).

A deterministic accept-by-default keeps actors runnable without a human in the loop; the DETERMINISTIC call-out bundle (BT-23) supplies the default.
Refines: EMB-15-001
EMB-15-013 MUST NOT The decision seam MUST NOT make the deciding actor's answer wait on another actor's approval. Only EvaluateEmbargoProposal decides whether the accept arm runs, whether or not the deciding actor is the Case Owner.

A participant's answer to an embargo Invite records only its own consent row (CM-18, ADR-0122), so the Case Owner has nothing to approve. A gate that asks another actor for a decision is a protocol ask, not a call-out point (BT-18-014). The CASE_MANAGER never runs this seam for its own consent. A gate where the Case Owner delegates activation to the CASE_MANAGER belongs on the CASE_MANAGER's activation path (#6045).
Extends: EMB-15-001
Refines: BT-18-014
EMB-15-006 MUST NOT When the deciding actor holds CVDRole.CASE_OWNER, the owner's stated response is authoritative and the seam MUST NOT require external approval.

The CASE_OWNER is the human decision-maker whose choice is gospel; requiring external approval for the owner's response would violate the authorization model.
Refines: EMB-15-013
EMB-15-003 SHOULD For Flow A (EP proposing terms), the decision seam SHOULD provide a counter-proposal arm gated by a WillingToCounterEmbargoProposal Evaluator call-out point.

A counter-proposal is operationally identical to proposing: the propose trigger already records a "counter-proposed, no state change" outcome when invoked in PROPOSED. Countering is intentionally low-automation and off by default; the recommended path is accept-then-revise.

ECA Details

Preconditions

- Flow A only; inbound EP received; actor declined to accept outright and the adjudication arm elects to counter
- EM state: PROPOSED

Steps

1. [system] Run WillingToCounterEmbargoProposal Evaluator call-out point → SUCCESS elects the counter arm; FAILURE (default) skips it

Postconditions

- The counter arm runs only when WillingToCounterEmbargoProposal succeeds

Extends: EMB-15-001
EMB-15-011 MUST NOT The counter-proposal arm (EMB-15-003) MUST NOT introduce a new mechanism. When the arm is taken, the seam delegates to the existing embargo proposal trigger, propose_embargo_trigger_bt via SvcProposeEmbargoUseCase. That trigger emits a fresh EP while the EM state remains PROPOSED.

Modeling counter as routing to the existing trigger avoids duplicate mechanism and keeps the EM lifecycle single-sourced.

ECA Details

Steps

1. [actor] Delegate to propose_embargo_trigger_bt with new terms → New EP emitted; EM remains PROPOSED (counter recorded)

Postconditions

- Counter EP emitted via the existing proposal mechanism; no new counter-specific transition introduced

Extends: EMB-15-003
EMB-15-012 SHOULD The default DETERMINISTIC backend for the WillingToCounterEmbargoProposal call-out point (EMB-15-003) SHOULD return FAILURE, so that the seam does not counter.

The recommended practice is to accept and then revise rather than to counter, so countering is off by default.
Extends: EMB-15-003
EMB-15-008 MUST When its embargo-response decision seam resolves to reject, this codebase MUST delegate to the existing rejection mechanism (EMB-15-004) rather than duplicate the transition. The mechanism follows the overture's flow: reject_embargo_trigger_bt for Flow A, and the invitee's Reject of the Invite for Flow B.

The rejection paths already carry the EM and consent semantics. If the decision layer re-implemented the transition, the two copies could drift apart, and a rejection could then change EM or consent in a way the rejection trigger does not. When the decision layer selects among the existing paths, one implementation decides each rejection.
Implements: EMB-15-004

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

Policy Record Format

ID Priority Requirement Related
EP-01-004 MUST The embargo policy record MUST be serializable as a Pydantic model and persisted in the DataLayer as part of the Actor's profile record (EP-01-001)

The policy must survive a restart and be readable from the profile at case creation (EP-04-003). Persisting it as part of the profile record keeps one copy, so the profile and the policy cannot disagree.
Uses definition from: EP-01-001

API Endpoint

ID Priority Requirement Related
EP-02-001 SHOULD Each Actor SHOULD expose its embargo policy at GET /actors/{actor_id}/embargo-policy

A coordinator evaluates an actor's terms before inviting it (EP-03-001). A predictable URL lets it fetch those terms from any server without knowing how that server lays out its profiles.
EP-02-002 MUST The policy endpoint MUST return its record as machine-readable JSON.

Compatibility evaluation is done by code (EP-03), so the policy must be machine-readable.
EP-02-006 MUST The policy endpoint MUST return the same record that the Actor's profile carries inline under embargo_policy (EP-01-001).

If the endpoint could return a record that differs from the one in the profile, a coordinator could evaluate terms the actor has since replaced.
Uses definition from: EP-01-001
EP-02-004 MUST NOT A publish or replace at PUT /actors/{actor_id}/embargo-policy MUST NOT overwrite an update to the actor's profile that was written after the request read it.

The policy is a field of the profile (EP-01-001), so a publish rewrites the whole profile, and a plain read-then-save loses a write that lands between the two without anyone being told.
Extends: EP-02-005
EP-02-007 MUST The policy endpoint MUST write a publish or replace only if the stored profile is still the one the request read.

A compare-and-set write is what keeps a publish from overwriting a profile update that landed after the request read the profile (EP-02-004).
Implements: EP-02-004
EP-02-008 MUST When the stored profile has changed since the request read it, the policy endpoint MUST re-read the profile and re-apply the request's terms.

Re-applying the terms to a fresh read is safe because a publish changes only the policy field, so a concurrent profile update and the published policy are both kept.
Extends: EP-02-007
EP-02-009 MUST When the profile keeps changing under the request for a bounded number of attempts, the policy endpoint MUST refuse the request with 409 Conflict.

The bound keeps a profile under continuous write from holding the request open.
Extends: EP-02-008
EP-02-010 MUST A publish or replace that the policy endpoint refuses with 409 Conflict MUST write nothing.

A refused request that wrote part of its change would leave the profile in a state no request asked for.
Extends: EP-02-009
EP-02-005 SHOULD A hosted Actor SHOULD be able to publish or replace its embargo policy at PUT /actors/{actor_id}/embargo-policy, with a body that carries only the terms (EP-01-002, EP-01-003).

Without a write endpoint the only way to give a Receiver an actor default is to reach into its store, so an operator could not set the terms shortest-wins reads at case creation.
Uses definition from: EP-01-002
Uses definition from: EP-01-003
EP-02-011 MUST The policy endpoint MUST derive the record's attributedTo from the addressed actor's own record, never from the request body.

Deriving attributedTo from the path actor keeps a body from publishing terms in another actor's name (EP-01-005).
Extends: EP-02-005
EP-02-012 MUST The policy endpoint MUST persist the record as the embargo_policy field of the addressed actor's profile, in that actor's own store (EP-01-004).

The profile then carries the record inline as the actor default that shortest-wins reads at case creation (CP-01-010, EP-04-003). A free-standing record beside the profile would be a second source that nothing reads.
Refines: EP-01-004
EP-02-013 MUST A replace at the policy endpoint MUST leave exactly one policy for the actor.

Writing the terms into the one profile field makes a replace an overwrite, so no withdrawn default is left beside the current one for anything to read.
Extends: EP-02-005

Default Embargo Semantics

ID Priority Requirement Related
EP-04-013 MUST NOT InitializeDefaultEmbargoNode MUST NOT persist the intermediate EM.PROPOSED state.

How this codebase meets EP-04-002; split from it so EP-04-002 states only what other participants observe (MS-12-010).
Implements: EP-04-002
EP-04-031 MUST This codebase MUST apply the PROPOSE and ACCEPT state machine triggers atomically within InitializeDefaultEmbargoNode.

How this codebase meets EP-04-002; split from it so EP-04-002 states only what other participants observe (MS-12-010). An atomic step leaves either the whole creation embargo or nothing.
Implements: EP-04-002
EP-04-014 MUST This codebase MUST carry the proposed EmbargoEvent of EP-04-004 inline as the proposedEmbargo of the Offer(VulnerabilityReport), not by reference.

How this codebase meets EP-04-004; split from it so EP-04-004 states only what other participants observe (MS-12-010). The CASE_MANAGER has never seen the Reporter's event, and this codebase dereferences only the few references AKM-05-007 lists, so the event travels inline. That is a shortcut of this prototype reference implementation, not a protocol rule.
Implements: EP-04-004
EP-04-015 MUST This codebase MUST make the protocol default embargo duration of EP-04-005 configurable per actor.

How this codebase lets a deployment choose its protocol default within the bounds EP-04-005 sets; split from it so EP-04-005 states only the bounds and the case that other participants observe (MS-12-010). Whether a value can be changed is an operating choice of one implementation.
Implements: EP-04-005
EP-04-032 MUST This codebase MUST refuse a configured protocol default embargo duration outside [72 hours, 5 days].

A configured value outside the bounds of EP-04-018 would let one deployment's default break the protocol rule that other participants rely on.
Implements: EP-04-018
EP-04-010 MUST NOT This codebase MUST NOT conflate the actor default with the protocol default.

A consumer must be able to tell "the CASE_OWNER published this duration" from "the CASE_OWNER published nothing". A fallback returned into the same blackboard key that a published EmbargoPolicy fills leaves no downstream code able to tell the two apart. See ADR-0096.
EP-04-022 MUST This codebase MUST carry the actor default and the protocol default under distinct names.

Distinct names are how a consumer distinguishes "the CASE_OWNER published this duration" from "the CASE_OWNER published nothing" (EP-04-010).
Implements: EP-04-010
EP-04-023 MUST The protocol default MUST be the only fallback embargo duration in this codebase.

A second implicit default duration would decide an embargo's length where nothing states it, and would hide which default a case received.
EP-04-012 MUST Creation-time embargo initialization MUST run at most once per case.

A second initialization stores a fresh EmbargoEvent for a case that already has its embargo history, which leaves an orphan write and an unanswerable proposal.
EP-04-028 MUST NOT This rule covers a Create(CaseProposal) that resolves to an existing VulnerabilityCase. Its receiver MUST NOT run creation-time embargo initialization again in any EM state but NONE: PROPOSED, ACTIVE, REVISE or EXITED.

"Initialized" cannot be read from the case's active-embargo reference, because termination clears that reference while the EM state stays EXITED. A guard keyed on the reference reads an exited case as uninitialized and runs the creation arm, which stores a fresh EmbargoEvent before the EM machine refuses the EXITED → PROPOSED step it has no transition for. The EM state is the evidence: the machine never returns to NONE once it has left it.
Refines: EP-04-012
EP-04-029 MUST NOT The CASE_MANAGER MUST NOT reconcile the embargo terms on a Create(CaseProposal) that resolves to an existing case against that case. Terms that conflict with the case lose to the case.

The embargo belongs to the case, not to the report. Skipping the whole creation arm is what leaves the proposal's terms unreconciled: the shortest-wins comparison and the pending-revision registration both live inside it.
Derives from: EP-04-028
EP-04-030 MUST For a case still at EM.NONE, creation-time embargo initialization MUST proceed.

A case still at EM.NONE has never been initialized, because EP-04-002 never persists PROPOSED, so NONE still admits the case the delivery is creating.

Embargo Invite RSVP Window Policy

Policy requirements for the embargo invite RSVP window: the fallback default when no deadline is on the wire, the minimum permitted window, and the clamp-on-receipt rule that neutralises coercively short deadlines. Codified by ADR-0065. Source: IDEA-2066.

ID Priority Requirement Related
EP-07-007 MUST This codebase MUST make the default RSVP window of EP-07-001, which is the policy window of CM-18-023, configurable per actor.

How this codebase lets a deployment choose the window; split from EP-07-001 and CM-18-023 so they state only the window and its default that other participants observe (MS-12-010). Whether the value can be changed is an operating choice of one implementation.
Implements: EP-07-001
Implements: CM-18-023
EP-07-008 MUST This codebase MUST make the minimum RSVP window of EP-07-002 configurable per actor.

How this codebase lets a deployment choose the minimum window; split from EP-07-002 so it states only the minimum and its default that other participants observe (MS-12-010). Whether the value can be changed is an operating choice of one implementation.
Implements: EP-07-002
EP-07-012 MUST This codebase MUST apply an actor's configured minimum RSVP window in both directions. It applies to the Invites the actor sends (EP-07-002) and to the clamp on those it receives (EP-07-003).

One configured value for both directions keeps an actor from demanding of others a window it does not grant to itself.
Extends: EP-07-008
Uses definition from: EP-07-003
See also: EP-07-002 — context for the reader
EP-07-005 MUST A receiving actor MUST log every deadline clamp it applies to an Invite(EmbargoEvent) deadline — both the EP-07-003 clamp up to the applicable minimum window and the EP-07-011 clamp down to the embargo's end_time.

Logging the clamp makes the adjustment observable for auditing and debugging without rejecting the invitation.
Extends: EP-07-003
Extends: EP-07-011

Open Proposal Resolution Order

How a Participant resolves two or more simultaneously open embargo proposals: earliest expiration first, with the remainder handled as revisions. Codified by ADR-0100, which also records why there is no multi-candidate poll activity. The heuristic itself predates this group as normative prose in docs/topics/process_models/em/defaults.md; stating it here is what makes it testable. Source: CONCERN-3433.

ID Priority Requirement Related
EP-08-003 MUST An implementation that records open embargo proposals MUST take a proposal out of that record when it is decided. A proposal is decided when it is accepted or rejected, or when its embargo terminates.

EP-08-002 orders the set of open proposals, so a set that retains decided proposals can select one that is no longer open. Ordering an unpruned record is not a weaker guarantee than ordering a pruned one — it is a different and wrong answer, which is why the retention rule is stated alongside the ordering rule rather than left as hygiene.
Constrains: EP-08-002

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-014 MUST This codebase MUST gate a trigger use case's write of shared EM state (EP-09-008) with the same CASE_MANAGER role gate the received trees use (BT-17-001).

How this codebase keeps a non-manager's trigger from writing shared EM state and tracks the ask it sent; split from EP-09-008 so that item states only what other participants observe (MS-12-010). The role gate and the pending-assertion store are this codebase's mechanism, and no other participant sees either.
Implements: EP-09-008
Uses definition from: BT-17-001
EP-09-018 MUST When the role gate of EP-09-014 refuses a trigger's write, this codebase MUST record the trigger's activity in the pending-assertion store (SYNC-11-002).

The record is how this codebase tracks the ask it sent to the CASE_MANAGER, so the answer can close it (EP-09-019). No other participant sees the store.
Extends: EP-09-017
Uses definition from: EP-09-014
Refines: SYNC-11-002
EP-09-019 MUST The CASE_MANAGER answers a refused ask with its Reject of the proposal, or of the Invite to a refused Accept (EMB-02-004). This codebase MUST close the pending entry of EP-09-018 when that answer arrives.

A pending entry that no answer closes would leave the ask open for good, so the actor would wait for an answer it already has.
Extends: EP-09-018
See also: EMB-02-004 — context for the reader
EP-09-015 MUST This codebase's accept and reject embargo triggers MUST resolve an Invite the caller names from the participant's own record of the Invites it received. They do not resolve it from the record of open proposals.

How this codebase's triggers find the Invite a participant answers; split from EP-09-012 so that item states only the answer other participants observe (MS-12-010). The record a trigger reads and the error it raises are this codebase's mechanism. A no-name call never falls back to the embargo in force, because answering an embargo is an intentional act.
Implements: EP-09-012
EP-09-029 MUST This codebase's accept and reject embargo triggers MUST raise a not-found error in two cases. The participant holds no Invite the caller names, or the Invite's row is not INVITED or TIMED_OUT (EP-09-027).

The error this codebase raises for an Invite with nothing to answer is its mechanism for refusing an answer the protocol forbids (EP-09-027).
Implements: EP-09-027
EP-09-030 MUST When the caller names no Invite, this codebase's accept and reject embargo triggers MUST select among the open proposals only (EP-08-002). They never select the embargo in force.

Answering an embargo in force is an intentional act, so a call that names nothing never falls back to it.
Implements: EP-08-002
EP-09-016 MUST This codebase MUST offer withdrawal (EP-09-013) as a trigger of its own. The trigger resolves the embargo from the case's active embargo and refuses, with a reported reason, a withdrawal the participant may not send (EP-09-028).

How this codebase exposes withdrawal to a participant's operator; split from EP-09-013 so that item states only the Leave other participants observe (MS-12-010). Which trigger sends it, and how a refused call is reported, are this codebase's mechanism.
Implements: EP-09-013
Implements: EP-09-028
EP-09-031 MUST NOT This codebase's accept and reject embargo triggers MUST NOT withdraw from the embargo in force.

Keeping withdrawal out of the reject trigger means a no-name reject still refuses an open proposal (EP-08-002) and never withdraws a signatory.
Implements: EP-09-013

Encryption

Requirements for encrypted messaging and actor key management using ActivityPub extension conventions. Ensures that sensitive vulnerability information can be protected in transit between actors.

File ID: ENC

Decryption Pipeline

ID Priority Requirement Related
ENC-03-001 MUST Decryption of inbound encrypted activities MUST occur in the inbox handler before the activity is passed to semantic extraction or dispatch

Semantic extraction and dispatch read the activity's type and objects, which an encrypted body hides. Decrypting first lets structure validation (IE-04-001) and every later stage work on the plaintext activity unchanged.
ENC-03-002 MUST If decryption fails, the inbox handler MUST return HTTP 400 with a structured error indicating decryption failure

An activity that cannot be decrypted cannot be validated or processed. A distinct error tells the sender that the failure was in decryption, for example a wrong or stale key, and not in the activity's content, so it can correct the cause and resend.
Uses definition from: EH-05-001
ENC-03-003 MUST NOT This codebase MUST NOT mix decryption logic into semantic extraction code.

Kept apart, extraction stays a mapping from plaintext AS2 to semantics that can be tested without keys, and the encryption scheme can change (ENC-02-002) without touching pattern matching. Mixed together, every pattern would have to handle both encrypted and plaintext forms.

Error Handling

Requirements for handling error conditions in the Vultron inbox handler, covering the exception hierarchy and error categories. Governs graceful degradation, clear error messages, system stability, and debuggability.

File ID: EH

Exception Hierarchy

ID Priority Requirement Related
EH-01-001 MUST The system MUST define custom exceptions for application-specific errors

A caller must tell an application failure apart from a bug in a library or in Python itself. A custom exception names the failure in domain terms. A caller can then catch exactly the failures it knows how to handle and let the others show as bugs.
EH-01-002 MUST Each custom exception outside vultron/metadata/ and vultron/bt/ MUST inherit from the base VultronError exception.

One base class lets a caller, such as the HTTP error handler, catch every application failure with one except clause, and other exceptions still show as bugs. The metadata loaders raise ValueError by contract, so that callers guard one exception pair (MS-17-004). The legacy simulator under vultron/bt/ is reference code that is not changed (ADR-0008), and its errors never reach the HTTP error handler.
EH-01-003 MUST This codebase MUST define in vultron/errors.py each error category that more than one of the core, wire and adapter layers raises.

An error that several layers raise needs one home. vultron/errors.py imports only the standard library, so every layer can import from it. An error that one subsystem raises goes in that subsystem's own errors.py (EH-02-001), as in vultron/wire/as2/errors.py. An outer layer may still catch it there, as the inbox adapter catches VultronParseError, because adapters may import wire.

Submodule Errors

ID Priority Requirement Related
EH-02-001 MUST Submodule-specific errors MUST be defined in submodule errors.py

An error that only one subsystem raises belongs next to the code that raises it. A local errors.py keeps the failures of that subsystem easy to find and keeps the shared module small.
EH-02-002 MUST Submodule errors MUST inherit from base custom exceptions in vultron/errors.py

A handler that catches VultronError or one of its categories also catches a subsystem error that inherits from them. A subsystem can then add its own errors, and the callers that already handle the general case need no change.

Error Categories

ID Priority Requirement Related
EH-03-001 MUST This codebase MUST define VultronValidationError in vultron/errors.py, the error category for malformed or schema-invalid input.

A caller decides what to do from the kind of failure, not from the message text. Bad input, a missing object, a protocol violation and a security failure each need a different response, for example a different HTTP status. Fixed categories give each of these responses one exception type to catch.
EH-03-003 MUST This codebase MUST define VultronNotFoundError in vultron/errors.py, the error category for a referenced domain object that does not exist.

A caller that holds a reference needs to tell a missing object apart from a bad request. The HTTP error handler answers a missing object with 404 and bad input with 422 (HTTP-03), and it can only do so when each has its own exception type.
Extends: EH-03-001
EH-03-004 MUST This codebase MUST define VultronInvalidStateTransitionError and VultronProtocolViolationError in vultron/errors.py, the error categories for an invalid state-machine transition and for invalid message semantics.

A protocol violation needs its own response: the HTTP error handler answers an invalid state-machine transition with 409, and the inbox background task drops a replayed item that raised VultronProtocolViolationError without a retry (IE-06-010). A caller can make neither choice from message text.
Extends: EH-03-001
EH-03-005 MUST This codebase MUST define, in vultron/errors.py, an error category for an authentication or authorization failure.

An authentication or authorization failure needs a response of its own, and it must not read as bad input or a missing object. A category for it lets the HTTP error handler and the logs tell it apart. VultronProofVerificationError is the category for a proof that is missing or does not verify, the authentication half. translate_domain_errors maps it to 422 under its own error name: the proof is content, not an HTTP credential, so 401 does not fit, and at the inbox a verified sender that is not entitled gets a Reject from core (HP-01-006), not a 403. VultronNotACaseParticipantError is the authorization half, answered 403 by the case-object read (AKM-05-006).
Extends: EH-03-001
EH-03-002 MAY This codebase MAY define more error categories in vultron/errors.py as it needs them.

The categories of EH-03-001 and the requirements that extend it are a floor. A failure that needs its own response can get its own exception type, and no caller has to tell it apart by message text.

Error Context

ID Priority Requirement Related
EH-04-001 SHOULD Exceptions SHOULD include contextual information

A message alone often does not tell an operator which activity, actor or object failed. Context on the exception, such as the activity ID, lets the log and the HTTP response point to the item that failed. The operator can then find the fault faster.

Error Response Format

ID Priority Requirement Related
EH-05-001 MUST HTTP error responses MUST include a structured JSON body with at minimum the following fields: error (string — machine-readable error code from the VultronError hierarchy), message (string — human-readable description), and status (integer — HTTP status code mirroring the response status).

A client must tell failures apart without reading prose. A fixed JSON body with a machine-readable code, a human-readable message and the status code gives every error response the same shape. One client parser can then handle all of them.
EH-05-002 MUST An HTTP error response that reports more than one distinct violation MUST include a details field, an array with one entry per violation.

When a request has several violations and the response names only one, the caller fixes one problem, sends the request again and learns of the next. The rejection is atomic, so nothing changed between the attempts. details gives one entry for each violation, so a caller does not have to parse message. Such a parse breaks when the order of the internal checks changes.
Extends: EH-05-001
Implements: EH-07-001
EH-05-003 MUST Each entry of the details array (EH-05-002) MUST carry the violation's human-readable message.

An entry without its own text tells the caller that a violation exists but not what it is. The caller would then have to match entries to parts of the joined message.
Extends: EH-05-002
EH-05-004 MUST Each entry of the details array (EH-05-002) MUST state whether its violation is a root cause or is derived from another reported violation.

One bad value often causes more violations. The label tells the caller which entries to fix first, so a long list stays readable (EH-07-002).
Extends: EH-05-002
Uses definition from: EH-07-002
EH-05-005 MUST When an HTTP error response reports more than one violation, its message field MUST stay a human-readable rendering of the whole set.

A caller that reads only message still sees every violation. Adding details then makes no text-only caller worse off.
Refines: EH-05-001

Error Logging

ID Priority Requirement Related
EH-06-001 MUST All errors MUST be logged at the level defined by SL-03-001 log level semantics

The log level of an error tells an operator how serious it is. One set of level rules (SL-03-001) keeps a recoverable fault from raising an alarm and keeps a real failure from being hidden at DEBUG.
Refines: SL-03-001

Multi-Violation Rejection

ID Priority Requirement Related
EH-07-001 MUST A validation boundary that rejects its input as a unit MUST report every violation it can recognise in that input, not only the first. Rejecting atomically does not license reporting a single reason: no partial progress was accepted, so a caller told one reason at a time gains nothing from the round trip.

Atomic rejection decides what the system writes. It does not decide what the system reports. A boundary that reports only the first violation makes the caller fix one problem at a time. Each attempt costs a round trip, and the boundary kept no partial work that could justify that cost.
EH-07-002 MUST When a validation boundary reports multiple violations, it MUST classify each violation as root or derived. A rule that reads one dimension is always root. A rule that reads more than one dimension is derived when a dimension it reads already carries a single-dimension violation. Otherwise it is root. Dimension overlap is a proxy for the real test, which is remediation. A violation is derived when the remediation the caller applies to the overlapping single-dimension violation also clears it. The proxy holds only while that premise does. For a transition fault, the expected remediation is to assert a legal value. That clears the entailment that read the illegal value. For a role gate, the expected remediation is to withdraw the assertion, not to acquire the role. A participant does not hold a dimension it has no role for (a non-DEPLOYER's d is absent, not initial; ADR-0075). An actor cannot grant itself a role. An author MUST check a new rule family whose expected remediation is neither of those against the remediation test before relying on the overlap proxy.

One bad dimension often causes more violations. A list that does not rank them becomes a long list of errors that one fix mostly clears. The root and derived labels tell the caller which violations to fix first. The label uses dimension overlap and not a graph of which rule depends on which. Thus a new rule whose fix is a legal value or a withdrawn assertion gets the correct label with no extra work. A root violation that reads several dimensions is the most useful one: each dimension moved legally on its own, but the combination is not possible. The overlap rule is correct only while the expected fix holds, so the statement names that fix. For a role gate the fix is to withdraw the assertion. A participant has no value on a dimension it has no role for (ADR-0075), so a role gate cannot mislabel its consequences.
Extends: EH-07-001
EH-07-003 MUST A VultronError subclass raised to report multiple violations MUST carry them as structured data on the exception. Then no caller has to parse a joined message to recover them.

DemoFailureError already establishes this shape for the demo runner (DEMOCI-01-003). Reusing it rather than inventing a second aggregation mechanism keeps one pattern for accumulate-all-then-fail, and lets the structured list reach the HTTP layer (EH-05-002) without new plumbing.
Refines: EH-04-001
EH-07-004 MUST A VultronError subclass raised to report multiple violations MUST render the whole set in str().

The HTTP layer and the logs use str() of the exception. When str() names every violation, a reader of the text alone still sees the whole set (EH-05-005).
Extends: EH-07-003

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-004 MUST An external decision node is a BT node that cannot complete autonomously: it requires input from an actor, a user interface, or an external system before it can return SUCCESS or FAILURE.

Some steps cannot complete without a decision from outside the actor. A fixed definition separates these points from steps that the actor must automate. A missing decision point and a missing automation are then not confused.

Cascade Implementation

ID Priority Requirement Related
EDF-03-001 MUST All cascade steps that do not require external input MUST be implemented as BT subtrees within the handling actor's BT execution context.

A BT subtree runs inside the same execution as the step that caused it, and the tree status reports its result. Procedural code after the tree runs outside it. The tree status then does not report a failure of that code, and its writes do not go through the checks that the BT write nodes apply.
EDF-03-002 MUST NOT A use case MUST NOT emit a cascade's outbox activity through a procedural call after BTBridge.execute_with_setup() returns.

An emission placed after execute_with_setup() returns can run when the tree failed. As a leaf node, the emission runs only when its tree reaches it, and the tree status reports its result.
EDF-03-003 MUST A use case's execute() method MUST contain only infrastructure glue: BT instantiation, blackboard setup, bridge execution, status check, and output extraction.

When execute() only builds, sets up and runs the tree, all protocol logic is in the tree, where nodes can be tested and composed. Logic in execute() is hidden from the tree. If that logic writes state, it skips the checks that the tree applies (CLP-10-020).
EDF-03-006 MUST This codebase MUST implement each outbox emission in a cascade as a BT leaf node, such as an EmitXxxNode.

A leaf node runs only when its tree reaches it, and the tree status reports its result. An emission in a leaf node then cannot run when an earlier step of the tree failed.
Implements: EDF-03-002

External Decision Nodes

ID Priority Requirement Related
EDF-04-002 MUST NOT An external decision node MUST NOT return py_trees.common.Status.RUNNING to show that it awaits input.

The execution model cannot host RUNNING: BTBridge.execute_tree treats root RUNNING as "continue ticking", exhausts its budget, logs ERROR, returns FAILURE, then discards the tree — so no node survives to be resumed. Waiting is instead expressed by requesting the input and terminating (ASK-01-002).
Refines: ASK-01-003
EDF-04-004 MUST Trigger endpoints that correspond to external decision node resolutions MUST be documented as such; their role is to supply the missing input, not to choreograph a cascade that should be automatic.

Without this documentation, a trigger that supplies a decision looks the same as a trigger that pushes a cascade that should run on its own. The documentation shows which triggers are correct uses and which ones hide a missing automation (EDF-05-005).
EDF-04-005 MUST NOT An external decision node MUST NOT succeed or fail without having requested the input it needs.

A decision point that returns a final status without a request hides that nobody asked for the input. The tree then continues as if somebody made the decision. A decision point stops and does not wait (EDF-04-002), so the emitted request is what shows "asked and waiting" and not "gave up". RequireCaseOwnerApprovalNode has this defect: it returns FAILURE and asks nobody.
Derives from: EDF-04-007
EDF-04-006 MUST NOT An external decision node MUST NOT be modeled as an absence of code.

An absent node makes the waiting point invisible to the BT structure, preventing inspection and making the decision requirement undetectable.
Derives from: EDF-04-001
EDF-04-007 MUST An external decision node MUST request the input it needs and then terminate.

No tree instance stays alive between events, so a node cannot wait inside the tree. The node shows that it waits by sending its request. The arrival of the input then starts a fresh evaluation (EDF-04-003).
Implements: EDF-04-002

Demo Constraints

ID Priority Requirement Related
EDF-05-001 MUST Demo scripts MUST inject only primary events into the system.

A demo shows what the system does on its own. When a demo injects only primary events, the system produced every other step that the demo observes. The demo then checks the cascades and does not hide gaps in them.
EDF-05-002 MUST NOT A demo script MUST NOT trigger an intermediate cascade step manually.

A manual trigger for a cascade step lets a demo pass when the system does not complete that step itself. The demo then hides the missing automation that it should show.
EDF-05-003 MUST Demo scripts MUST verify correctness by observing externally visible system state (e.g., DataLayer contents, activities queued in the outbox) after the primary event and its cascades have settled.

"Settled" is not a matter of elapsed time. EDF-06 defines normatively what counts as evidence that a cascade has settled; read this requirement together with EDF-06-001.
Uses definition from: EDF-06-001 — EDF-06-001 supplies the operational definition of "settled" that this requirement assumes.
EDF-05-004 MUST NOT Demo scripts MUST NOT assert on internal BT execution state (e.g., node status, blackboard values) as a substitute for observing external system state.

Node status and blackboard values are internal, and they change when the tree changes. External state is what a peer or an operator sees. A check on external state tests the behavior and still holds when the tree changes shape.
EDF-05-005 SHOULD A demo that must manually trigger intermediate steps to reach its expected final state SHOULD be treated as evidence of a cascade automation gap that requires a BT fix, not as correct demo behavior.

A demo that needs a manual step shows that the system does not complete a cascade on its own. When that need counts as a defect, the fix goes into the tree, and the demo does not hide the gap.
EDF-05-006 MUST The handling actor MUST complete each cascade step that is not an external decision node automatically, as a result of the primary event.

A demo may inject only primary events (EDF-05-001). Each later step must then follow from the primary event alone. Otherwise the demo cannot reach its final state without a manual trigger.
Refines: EDF-03-004

Causal Gating in Demo Scenarios

ID Priority Requirement Related
EDF-06-002 MUST The harness MUST evaluate a gate predicate against the state of the actor that owns the awaited effect, read from that actor's own container.

Each actor holds an independent DataLayer replica. A sender-side observation proves only that the sender emitted the activity, not that the recipient processed it.
EDF-06-003 MUST NOT A gate MUST NOT be placed on an observable that becomes true synchronously during the triggering request when the awaited effect is committed asynchronously after that request returns.

An observable that becomes true during the triggering request shows only that the cause started, not that it completed. The awaited effect commits after the request returns, so a gate on that observable lets the next step run before the effect it needs. A gate on the committed effect removes that race (ADR-0058).
EDF-06-004 MUST A received-side use case can create a new activity in response to a received one, as in the forwarding or propose-then-execute pattern. The harness MUST find that derived activity by scanning the recipient's state for its activity type, target and object.

In the forwarding and propose-then-execute patterns, the recipient gets a new activity under an id that the received-side use case derives, and not the sender's activity. For example, on an ownership-transfer proposal from the Case Owner, the CASE_MANAGER makes its own Offer(VulnerabilityCase) for the transferee under a derived id (CM-21-028, ADR-0148). A poll for the id of the sender's activity can never find the derived activity. A scan for its type, target and object can find it.
EDF-06-005 MUST An unmet causal gate MUST prevent execution of the steps that depend on it. Recording the failure and continuing to the dependent step is not sufficient.

A gate that records a failure but lets the dependent step run produces a cascade of secondary failures that masks the first one, and makes the gate indistinguishable from a comment. This refines the accumulate-and-continue rule of DEMOCI-01-003, which governs reporting rather than control flow.
Constrains: DEMOCI-01-003 — Accumulation of failures is preserved; only the control flow of dependent steps is constrained.
EDF-06-006 MUST The harness MUST mark each irreducibly temporal wait as temporal at its call site. Service liveness probes, protocol deadlines such as embargo expiry, and transport retry backoff are such waits.

Not every wait is a defect. Naming the temporal waits explicitly keeps them from being "fixed" into meaningless causal gates, and keeps the causal-gate inventory honest about what it does and does not cover.
EDF-06-007 SHOULD A scenario author SHOULD treat a step whose causal precondition has no observable predicate as evidence of a missing observable or an unautomated cascade.

Refines EDF-05-005 to the harness side: where EDF-05-005 detects missing cascade automation from a needed manual trigger, this detects it from an ungateable precondition. Some preconditions are genuinely unobservable today (an actor having processed a delivery leaves no completion record); those gaps belong in the record, not behind a sleep.
EDF-06-008 MUST The timeout value of a temporal wait (EDF-06-006) MUST be accompanied by a comment at the call site that names the delivery chain being bounded and justifies the chosen value relative to worst-case BackgroundTasks delivery across the containers involved.

A bare integer timeout (e.g. timeout_seconds=15.0) with no explanation is indistinguishable from an arbitrary guess. When the wait starts failing in CI, there is no basis for deciding whether to raise the budget, change the observable, or investigate a deeper delivery failure. The justification comment is the decision record that makes that choice tractable.
Extends: EDF-06-006 — Adds a justification requirement to the identification requirement; both apply to every temporal wait.
EDF-06-010 MUST NOT The harness MUST NOT accept an effect seen in the sending actor's container as evidence that the receiving actor committed it.

Each actor holds an independent DataLayer replica. An effect seen on the sender's side proves only that the sender emitted the activity. It does not prove that the recipient processed it.
Derives from: EDF-06-002
EDF-06-011 MUST NOT For a derived activity (EDF-06-004), the harness MUST NOT poll for the id of the sender's original activity.

The recipient holds the derived activity under an id that the received-side use case derives. It does not hold the sender's activity under the sender's id. A poll for that id can never succeed.
Extends: EDF-06-004
EDF-06-012 MUST NOT The harness MUST NOT count a temporal wait (EDF-06-006) as a causal gate.

A temporal wait does not show that an effect was committed. If the causal-gate inventory counts it, the inventory claims coverage that it does not have.
Uses definition from: EDF-06-006
EDF-06-013 SHOULD A scenario author SHOULD record a step with no observable causal predicate (EDF-06-007) as a gap, and not replace its gate with a timed wait.

A timed wait hides the gap and makes the scenario race delivery. A record of the gap keeps it visible, so a later change can add the missing observable or automation.
Extends: EDF-06-007
EDF-06-014 MUST NOT A demo step MUST NOT run with a placeholder standing in for a value that an earlier step failed to produce.

EDF-06-005 governs whether a dependent step runs, not what it is given. A step that runs with None or "" in place of its value sends a request built on nothing, and its own failure hides the first one. The rule is about what reaches the next step, a bare argument or a field in a request body alike. Nesting the step inside the block that produces the value, or guarding each later read, keeps the placeholder out (ADR-0058).
Refines: EDF-06-005

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-001 MUST Each handler use-case class MUST accept (dl, request) as its __init__ parameters. Here dl is a narrow persistence port (CasePersistence or CaseOutboxPersistence, DL-07), and request is the handler's concrete VultronEvent subclass.

The dispatcher builds each handler the same way from a registry entry. Each handler gets the same two positional arguments, and the dispatcher passes any driven ports by keyword. A narrow port limits what a handler can write (DL-07). A typed request shows that its fields were validated before dispatch.
HP-01-013 MUST The execute() method of each handler use-case class MUST take no arguments.

The dispatcher calls execute() the same way for every handler. All input comes through the constructor, so a handler cannot depend on an argument that one caller passes and another caller does not.
Extends: HP-01-001
HP-01-002 MUST Handler use-case execute methods MUST return HandlerResult; None is not a permitted return type

The return value has a consumer: the handler's HandlerDisposition is the only thing that can tell InboxOutcome whether an inbound assertion was applied, skipped, deferred, or refused (ADR-0095). A permitted -> None would be ambiguous between "nothing to report" and "not yet migrated" and would contradict UCORG-05-002.
Refines: UCORG-05-002
HP-01-003 MUST A handler MUST report a HandlerDisposition of REFUSED only when it rejected the inbound assertion.

A behavior-tree FAILURE is not always a refusal, and a SUCCESS is not always applied work. An idempotent skip ends in SUCCESS, for example a status that is already present. An entry that the ledger-sync buffer only holds for later also ends in SUCCESS. If a handler reported either one as a refusal, the pipeline would set InboxOutcome.status == "rejected" and give false alarms. If a handler reported a deferral as APPLIED or SKIPPED, it would hide that a replay is pending (ADR-0095).
HP-01-014 MUST A handler MUST report SKIPPED for a legitimate no-op, such as a duplicate of a message already applied or still waiting, or an already-present record. A resend of a message the receiver refused is not such a duplicate: the seen-before door refuses it again with the reason its receipt stub recorded (CLP-10-010).

An idempotent skip ends in a behavior-tree SUCCESS, but it changes nothing. SKIPPED tells the pipeline that the message was handled without new work, so a redelivery does not read as applied work or as a refusal (ADR-0095). A refusal is whole and final for that activity, so its resend gets the same answer, not a skip (ADR-0214).
Extends: HP-01-003
Uses definition from: CLP-10-010
HP-01-015 MUST A handler MUST report DEFERRED when it parked the item for later replay and did not decline it.

An entry that the ledger-sync buffer holds for later ends in a behavior-tree SUCCESS, but its work is still pending. If a handler reported it as APPLIED or SKIPPED, nobody could see that a replay is pending (ADR-0095).
Extends: HP-01-003
HP-01-016 MUST NOT A handler MUST NOT report a benign skip or a deferral as REFUSED.

The pipeline maps REFUSED onto InboxOutcome.status == "rejected". A skip or a deferral reported as a refusal would then raise a false alarm for a message that the handler handled correctly (ADR-0095).
Extends: HP-01-003
HP-01-004 MUST NOT Handler use cases MUST NOT return or reference InboxOutcome or its processed/deferred/rejected vocabulary; mapping HandlerDisposition onto InboxOutcome is owned by DispatchNode

Keeps the inbox-pipeline vocabulary out of the core use-case layer. A handler reports what it did, in its own vocabulary; whether that becomes processed, deferred, or rejected is a pipeline concern, and two dispositions already collapse onto processed. Note this is a layering rule, not a claim about which outcomes a handler can cause: a handler can produce a deferral (HandlerDisposition.DEFERRED), it just must not say so in InboxOutcome's words.
HP-01-005 MUST A handler MUST report REFUSED for a message it has no role or addressing to act on, with a reason that names what is missing. One such message is a CASE_MANAGER-addressed message at an actor that is not the case's CASE_MANAGER. Another is a copy of an activity whose to does not name the receiving actor. cc, bto and bcc address no Vultron recipient (OX-08-001, ADR-0109). A cc-only receiver thus holds such a copy, of an Offer(VulnerabilityReport) (HP-09-001, HP-09-002, HP-10-001) as of any other activity.

The disposition is the receiver's report on its own handling (HP-01-004). If the receiver cannot act on a message, the sender addressed it to the wrong party. A courtesy copy gives no standing to act. REFUSED with a reason records both cases. The first receipt of a message that waits for the receiver's own decision is APPLIED: the first Offer(CaseParticipant) at the Case Owner, or a participant's first notice of its removal or reinstatement (CM-31-006, CM-31-011).
Constrains: HP-01-010
Constrains: HP-10-001
See also: HP-09-001 — context for the reader
See also: HP-09-002 — context for the reader
See also: OX-08-001 — context for the reader
HP-01-017 MUST NOT A handler MUST NOT report a receipt that HP-01-005 refuses as SKIPPED. That disposition is only for a duplicate or other idempotent re-delivery of a message that the receiver was entitled to act on.

A role gate returns SUCCESS when it skips (BT-17-001). If a handler reported that skip as SKIPPED, DispatchNode would record it as processed. The inbox would then show a misaddressed message as a successful receipt.
Extends: HP-01-005
HP-01-011 MUST CreateReportReceivedUseCase and SubmitReportReceivedUseCase MUST declare the ANY_ACTOR entitlement kind for HP-01-010, not an exemption.

ANY_ACTOR states a decided rule with no guard to compose, so it is a kind rather than an exemption: the occasion table's "Sent by" can render it (MSM-08-005), and the exemption list keeps only the checks that are still missing. Restricting it to the two new-report use cases stops it from becoming an exemption under another name.
Implements: HP-01-010
Refines: HP-01-007
HP-01-031 MUST NOT A received use case other than the two that HP-01-011 names MUST NOT declare ANY_ACTOR.

ANY_ACTOR composes no guard. If any other use case could declare it, it would become an exemption under another name, and the exemption list would no longer show every missing check.
Extends: HP-01-011

Payload Access

ID Priority Requirement Related
HP-04-001 MUST A handler MUST read activity data as typed fields of its VultronEvent subclass. These fields include the core VultronActivity on activity when the semantic entry sets include_activity.

The dispatcher hands a handler a fully validated domain event, so every field the handler needs is already typed, and required where the subclass declares it required. Reading the wire payload again would duplicate the single extraction seam (ARCH-03-001, ARCH-07-001) and reintroduce the optional-field guards that validate-at-edge removed (ADR-0032); core does not re-read wire activities for semantics (ADR-0035).
Refines: ARCH-07-001
Depends on: ARCH-08-002
HP-04-002 MUST NOT A handler MUST NOT re-parse, re-extract or otherwise re-read the inbound wire activity. Extraction and validation happen once, in the wire layer, before dispatch.

A second read of the wire payload would duplicate the single extraction seam (ARCH-03-001, ARCH-07-001). It would also bring back the optional-field guards that validate-at-edge removed (ADR-0032). Core does not re-read wire activities for semantics (ADR-0035).
Extends: HP-04-001

Logging

ID Priority Requirement Related
HP-06-001 MUST Handler entry MUST be logged at DEBUG level with the handler class name

DispatcherBase._handle() emits the entry line immediately before it calls execute(), so every handler gets it from one place and no handler carries its own copy.
HP-06-002 MUST Handlers MUST log state transitions at INFO level with before/after states

State transitions are the lifecycle events that an operator monitors, and INFO is the level for them (SL-03). When the log gives the state before and after the transition, a reader sees what changed and from what state. Thus DEBUG is not necessary.
HP-06-003 MUST Handlers MUST log errors at ERROR level with full context

An operator who diagnoses a failed message has only the log. An ERROR record that names the activity, the actor and the traceback lets the operator find the message and the cause. The operator does not need to reproduce the failure.
Refines: SL-03-001

Data Model Persistence

ID Priority Requirement Related
HP-08-001 MUST A persistence write made on a handler's behalf MUST go through the persistence port's typed object methods. These are dl.save(obj) (upsert) and dl.create(obj) (insert) with a domain object, which validate and dehydrate the model.

save() and create() are the write paths that keep the stored record consistent with the domain model and that dl.read() can rehydrate (ADR-0034). The record-level method is retained only as a compatibility shim for the adapter layer and for the legacy generic UpdateObject / CreateObject BT nodes in vultron/core/behaviors/helpers/object_nodes.py.
HP-08-002 MUST NOT A handler's execute() MUST NOT mutate the DataLayer directly (save, create, update, delete); the write runs inside a BT leaf node reached through BTBridge, so it sits on the audited ledger-commit path (CLP-10-005, BT-15-001).

The behavior tree runs the guard, the ledger commit and the effects in order. A write made directly in execute() skips the guards and has no ledger entry. Then the case changes, and no audited record shows who changed it.
Derives from: CLP-10-005
See also: BT-15-001 — context for the reader
HP-08-003 MUST NOT Pydantic validators MUST NOT overwrite existing field values during deserialization

If a validator overwrote a field on load, each read of the object would replace stored or received data with a default. Defaults can fill only empty fields, so a read gives back what was stored.
HP-08-004 MUST The DataLayer and handlers MUST treat object IDs as opaque URI strings

Object ids are URIs, and each implementation can mint them in its own form. Code that parsed an id, or expected a structure in it, would break on ids from a different implementation. It would also tie this codebase to one id scheme.
HP-08-005 MUST Handlers that add status updates MUST append full status objects (not bare ID strings) to the case/participant status history lists

Readers of a status history need the state and the time of each entry. A bare id carries neither. The history cannot validate a bare id when it appends it, so the history could hold references to objects that do not exist.
HP-08-006 MUST The AddNoteToCaseReceivedUseCase handler MUST persist the carried Note, then append its id to VulnerabilityCase.notes and commit the attachment as a ledger entry.

The handler stores each note and links it to its case, as the case management data model requires. The refusal uses only the id. The inbox routing rebuild gives the handler the stored note, not the carried note (IO-03-004). Thus a rule that compares the two copies could never find a difference on the inbox path. Without the refusal, an Add that names a note of a different case would attach it. Its content would then go to the participants of the target case.
Depends on: IO-03-004
HP-08-007 MUST A received Add(Note) or Add(CaseStatus) whose object's context is not the case the Add acts on, or names no case, MUST be refused before the commit. That case is a note Add's target and a case status Add's context (ADR-0204). The object checked is the one the handler would attach: the record stored under the object's id when one is held, else the carried copy.

A note or status belongs to one case. If a handler attached an object of a different case, it would commit that object to the case ledger of the target case. It would also send the object to the participants of the target case. The check uses the stored record, because the inbox routes the stored record (IO-03-004).
Extends: HP-08-006
HP-08-008 MUST A receiver MUST apply a received Add(ParticipantStatus) to the case its record of the target participant names, never to one a context field names.

The receiver appends the status to the participant record that it holds. Thus the case that owns that record is the case that changes. Suppose that the status of the sender selected the case. Then the sender guard, the commit and the case-status update would run on one case. The status itself would go to a participant of a different case.
Depends on: IO-03-004
HP-08-009 MUST NOT A persistence write made on a handler's behalf MUST NOT build a record by hand (object_to_record()) or call the record-level update(id_, record) compatibility method.

A hand-built record skips the validation and dehydration that save() and create() apply. dl.read() may then fail to rehydrate it (ADR-0034). The record-level method stays only as a compatibility shim for the adapter layer and the legacy generic BT nodes.
Extends: HP-08-001
HP-08-010 MUST The AddNoteToCaseReceivedUseCase handler MUST refuse an Add(Note) before the commit when a note is already stored under the carried note's id. It does so whatever the carried note says. The exception is a redelivery that HP-08-011 covers.

An Add(Note) introduces a new note. The inbox routing rebuild gives the handler the stored note, not the carried note (IO-03-004), so only the id can show the clash. Without the refusal, an Add that names a note of a different case would attach it, and its content would go to the wrong participants.
Extends: HP-08-006
Depends on: IO-03-004
HP-08-011 MUST When the case's ledger already records the same Add(Note), the AddNoteToCaseReceivedUseCase handler MUST report it as a SKIPPED redelivery.

A redelivery of an Add that the ledger holds is not a new note and not a clash. Reporting it as SKIPPED keeps a sender retry from reading as a refusal, and the note is attached only once (HP-01-014).
Extends: HP-08-006
Supersedes: HP-08-010
HP-08-012 MUST NOT The AddNoteToCaseReceivedUseCase handler MUST NOT replace a stored note. A change to a note would be an Update(Note), which this implementation does not route.

A replaced note would change content that the case's participants already received under that id. An Add only introduces a note, so it must never overwrite one.
Extends: HP-08-006
HP-08-013 MUST The receiver MUST refuse, before the commit, an Add(ParticipantStatus) whose status context is not the case that HP-08-008 names. HP-08-007 refuses an object of another case in the same way.

The status would otherwise go to a participant of one case while the sender guard, the commit and the case-status update ran on another.
Extends: HP-08-008
See also: HP-08-007 — an analogy: the same refusal for another object type
HP-08-014 MUST The receiver MUST refuse an Add(ParticipantStatus) before the commit when it holds no record of the target participant, or when that record names no case.

Without a stored record of the target participant, the Add has no case to act on. A commit on some other case would change a case that the status does not belong to.
Extends: HP-08-008
HP-08-015 MUST A receiver MUST refuse any received activity in which two context values, on the activity or an object down its object chain, name different cases. The chain is the activity's object and, when that object is an activity, the inner activity's own object, at any depth. An object named by a URI, a Link or a typed reference (MV-10-011) carries no context and is not compared. The chain ends at a Refuse, whose object is the refused act quoted as it arrived (CLP-05-001).

Two parts naming different cases say two things about where the act belongs, and acting on either would ignore the other. Every value compared is in the message, so the check needs no receiver state and runs at the parse edge (ADR-0032). A refusal notice's quoted act may carry an object of another case (HP-08-007). The quote is evidence of what arrived, not a part of the notice, so the participant can still read it (CLP-06-006).
Uses definition from: MV-10-011
Uses definition from: CLP-05-001
HP-08-016 MUST A refusal under HP-08-015 MUST name in its reason each context position that names a case, and the case it names.

The sender has to see which parts disagree to correct the message. A reason that named only one case, or no position, would leave it guessing which part to change. Every part is named at once, as for any refusal at a validation boundary (EH-07-001).
Extends: HP-08-015

Unsupported Addressing Fields

ID Priority Requirement Related
HP-10-002 MUST When this codebase discards an Offer(VulnerabilityReport) that names the receiving actor only in cc (HP-10-001), it MUST log a WARNING naming cc.

The discarded report never reaches a case, so the log record is the only trace an operator has that a sender addressed this actor in the wrong field.
Extends: HP-10-001

History File Management

Defines the structure, location, entry format, and tooling for managing project history entries. For implementation and idea types whose --source is ISSUE-N, append-history posts the entry body as a comment on GitHub issue N rather than writing a file. learning and priority types continue to write per-entry write-once files under plan/history/, managed by the append-history CLI tool.

File ID: HM

Entry File Format

ID Priority Requirement Related
HM-02-002 MUST Valid type values MUST be defined as a StrEnum named HistoryEntryType in vultron/metadata/history/types.py. Current values are idea, implementation, learning, and priority.

Every reader and writer gets the valid entry types from one enum in one module. Thus the CLI, the frontmatter model and the index always agree on which types exist.
HM-02-005 MUST Adding a new history entry type MUST only require adding a member to the HistoryEntryType enum; no other code changes are required for the tool to accept the new type.

If the type set had copies in several places, a new type would need an edit to each copy. A missed copy would reject valid entries. All code derives the types from the enum, so the enum is the only edit.
Extends: HM-02-002

append-history CLI Tool

ID Priority Requirement Related
HM-03-001 MUST The tool MUST be invokable as uv run append-history <type> where <type> is one of the valid HistoryEntryType values (see HM-02-002).

With one typed entry point, skills write history the same way each time, and the tool validates the type before it writes anything.
Uses definition from: HM-02-002
HM-03-009 MUST Passing an unrecognised <type> to append-history MUST produce a clear error message and exit non-zero.

If the type has a typo, the tool can file the entry in the wrong place or fail without a reason. A clear error and a non-zero exit stop the calling skill before it reports success.
Extends: HM-03-001
HM-03-002 MUST When no --file argument is given, the tool MUST read entry content from standard input (stdin). This enables pipeline use: echo "..." &#124; uv run append-history idea.

Skills generate entry bodies in the shell, so reading stdin lets them pipe the body directly without creating a temporary file.
HM-03-003 MUST The tool MUST accept a --file <path> argument as an alternative to stdin. When --file is given, content is read from the specified file rather than stdin.

Some bodies are long or are already in a file. Shell quoting into stdin can break such bodies. A file argument prevents this problem.
HM-03-004 MUST The tool MUST determine the target month directory using the current system clock (datetime.date.today()) during normal operation.

The tool takes the month from the clock, so the directory always agrees with the time the entry is written. Thus an agent cannot file an entry under the wrong month, on purpose or by mistake.
HM-03-005 MUST The tool MUST create plan/history/YYMM/ and plan/history/YYMM/<type>/ if they do not already exist before writing the entry file.

The first entry of each month and of each type goes into a directory that does not exist yet. The tool creates the directory, so callers do not need a separate setup step. A write never fails because a directory is missing.
HM-03-006 MUST After writing a new entry file, the tool MUST regenerate plan/history/YYMM/README.md by scanning the known-type subdirectories (idea/, implementation/, learning/, priority/), reading each entry file's frontmatter, and writing a summary table sorted by timestamp descending.

A table with the newest entries first gives a quick local view of the records for a month. The reader does not have to open each file. The tool scans only the known-type subdirectories, so unrelated files with different frontmatter cannot break the regeneration. The index is derived fully from entry frontmatter, so a local regeneration can rebuild it at any time.
HM-03-007 MUST The append-history tool's Python module MUST reside under vultron/metadata/history/ as a sibling of vultron/metadata/specs/.

The history tool is project metadata tooling, as are the spec and notes tools. These tools do not depend on the protocol code. When they stay together under vultron/metadata/, that layer stays separate from the application packages.
HM-03-010 MUST The append-history entry point function MUST be vultron.metadata.history.cli:main.

Skills, docs and the script registration all use this entry point by name. A fixed function name keeps these references correct when the internal structure of the module changes.
Refines: HM-03-007
HM-03-008 MUST The tool MUST be registered in pyproject.toml under [project.scripts] as append-history = "vultron.metadata.history.cli:main".

The [project.scripts] registration makes uv run append-history work, and every skill uses that command.
HM-03-011 MAY A backfill-only date override MAY exist for migration tooling so legacy entries can be written into historical YYMM directories.

Entries from older history formats must go into the month that they record, not the month of the migration. Migration tooling thus needs a way to set the date.

Timestamp Field and Future-Date Rejection

ID Priority Requirement Related
HM-06-007 MUST The append-history tool MUST populate the timestamp field automatically from the current system clock when creating new entries.

A timestamp that the caller types can be wrong. The tool takes the timestamp from the clock at write time, so the timestamp shows when the entry was really written.
Implements: HM-06-001
HM-06-002 MUST HistoryEntryFrontmatter MUST require a timestamp field that holds a timezone-aware ISO 8601 datetime in UTC.

Readers sort and file entries by timestamp. They cannot place an entry with a missing or unparseable timestamp.
HM-06-010 MUST HistoryEntryFrontmatter validation MUST fail with a clear error when timestamp is absent or malformed.

Validation finds a bad timestamp when the entry is written. A clear error names the timestamp problem, so the writer can correct the value.
Extends: HM-06-002
HM-06-004 MUST HistoryEntryFrontmatter MUST reject any timestamp value that is more than 60 seconds in the future (relative to the current UTC system clock). This tolerance accounts for clock drift between the time the timestamp is computed and when the Pydantic model is validated.

A future timestamp puts the index in the wrong order and records an event that did not occur yet. The 60-second tolerance covers the short delay between the time the tool computes the timestamp and the time it validates it.
HM-06-008 MUST Naive datetime values (those without a UTC offset) MUST be rejected with a clear error message.

The tool cannot convert a naive datetime to UTC unless it guesses the time zone of the writer. A clear error tells the writer how to correct the value.
Refines: HM-06-005
HM-06-009 MUST All stored and compared timestamps MUST be normalised to UTC.

Comparisons of timestamps with different offsets can easily go wrong. The month directory and the index columns both use the UTC value. When all values are in UTC, every comparison uses one representation.
Extends: HM-06-005
HM-06-006 MUST The plan/history/YYMM/README.md index MUST display a Date column, the YYYY-MM-DD part of timestamp, and a Time (UTC) column, the HH:MM part of timestamp.

Agents often write several entries on one day, so the date alone cannot show their order. A UTC time column shows when each entry was written.
HM-06-011 MUST The append-history tool MUST sort the entries of the plan/history/YYMM/README.md index by timestamp in descending order.

A newest-first sort shows the most recent work first, in the sequence it occurred.

CLI Interface for Frontmatter Construction

ID Priority Requirement Related
HM-07-001 MUST The append-history <type> command MUST accept --title and --source as required named arguments.

The title and the source make an entry easy to find. Because they are required named arguments, the tool writes no entry without them.
HM-07-005 MUST The tool MUST build the YAML frontmatter block itself, from the --title and --source arguments and the auto-generated timestamp.

When callers write frontmatter by hand, its format becomes different from the model, and the entries fail validation later. The tool builds the frontmatter from validated arguments, so the frontmatter of each entry is correct by construction.
Uses definition from: HM-07-001
HM-07-002 MUST NOT Callers of append-history MUST NOT include a YAML frontmatter block in the content they supply via stdin or --file.

If a caller supplies a frontmatter block, the body gets a second block, or the block conflicts with the block that the tool builds. When callers supply only body text, the tool is the only author of frontmatter.
Derives from: HM-07-005
HM-07-003 MUST The tool MUST accept a hidden --timestamp argument for backfill use only (e.g., migrating pre-existing entries).

A migration of pre-existing entries must keep their original times, and the clock cannot supply these times. The argument is hidden, so it is not part of the normal interface that skills use.
HM-07-006 MUST The --timestamp override argument MUST accept an ISO 8601 datetime string with a UTC offset.

The override must give the same tz-aware value as the clock path. Thus it accepts only an ISO 8601 string with a UTC offset.
Refines: HM-07-003
HM-07-007 MUST The standard future-date validation (HM-06-004) MUST apply to values supplied via the --timestamp override argument.

The override sets the time. It does not skip validation. The same future-date check applies, so backfilled entries obey the same rules as all other entries.
Extends: HM-07-003
Refines: HM-06-004
HM-07-004 MUST Skill documentation (plan-issue, build, learn) and notes/history-management.md MUST use the --title/--source interface for append-history.

Agents copy the command that skills and notes show, so the documentation must show the interface that the tool accepts.
HM-07-008 MUST NOT Skill documentation and notes/history-management.md MUST NOT use the frontmatter-in-stdin pattern for append-history.

Agents copy the command that skills and notes show. If the documentation shows the frontmatter-in-stdin pattern, agents learn a form that HM-07-002 forbids.

GitHub Comment Output Mode

ID Priority Requirement Related
HM-08-001 MUST When append-history is invoked with type implementation or idea and --source ISSUE-N, where N is a positive integer with no leading zero and gh issue view N finds an issue (not a pull request) in the CERTCC/Vultron repository, the tool MUST post the entry body as a comment on issue N using gh issue comment, rather than writing a file under plan/history/.

An implementation or idea record for an issue is most useful on that issue, where all readers of the issue find it. The tool posts the record there, so the record stays with its work item. The project then does not commit a file for each completed task. Only the ISSUE- prefix means an issue: sources such as ADR-0041, VCR-005 or BUG-2505 use other numberings, and reading their numbers as issues would post records on unrelated issues.
HM-08-002 MUST When append-history falls through to GitHub comment mode (HM-08-001), it MUST print the URL of the newly created comment to stdout so callers can record it.

The comment URL is the only reference to the record. Callers such as archive-history need it to link the record from the work that they report.
Extends: HM-08-001
HM-08-003 MUST When append-history is invoked with type implementation and --source ISSUE-N-<slug> (a lowercase, hyphen-separated slug), or with type idea and --source IDEA-YYMMDDNN (eight digits: a date and a sequence number), the tool MUST write the entry as a file under plan/history/ without asking GitHub.

Not every record of these types belongs in an issue comment. An ISSUE-N-<slug> implementation entry holds detail too long for a PR body, beside the completion comment on issue N (pr-body-guide.md § "Spec amended"). An IDEA-YYMMDDNN idea has no issue yet. A file under plan/history/ gives each a record, in the archive that the other entry types already use.
HM-08-004 MUST NOT The archive-history skill MUST NOT call git add plan/history/ or commit any file when the entry was posted as a GitHub comment (HM-08-001). The git add and commit steps are only needed for file-mode entries.

In comment mode the tool writes no file. A git add and a commit would thus fail, or they would commit unrelated staged changes.
Derives from: HM-08-001
HM-08-005 MUST The comment body posted to GitHub MUST contain the full entry body text (same content that would have been the Markdown body in the file-based format), prefixed with a one-line heading showing the entry type and title.

In comment mode the comment is the full record, so it must contain the same content as a file entry. The heading shows the entry type and title, so a reader can identify the entry among the other comments on the issue.
HM-08-006 SHOULD The archive-history skill documentation SHOULD be updated to reflect that when append-history outputs a GitHub comment URL (rather than a file path), the commit/push steps are skipped for that entry.

Callers of archive-history do the steps that its documentation gives. Without this guidance, they would try to stage and push a file that comment mode did not write.
HM-08-007 MUST When gh cannot answer whether the issue that an implementation or idea entry's --source ISSUE-N names exists (HM-08-001), append-history MUST exit non-zero and write no file and no comment.

A lookup that fails says nothing about the issue. Taking it as "no issue" would refuse a valid record, and taking it as "an issue" would post where no issue may exist; stopping lets the caller retry once gh works.
Depends on: HM-08-001
HM-08-008 MUST When append-history is invoked with type implementation or idea and a --source that is neither ISSUE-N (HM-08-001) nor that type's file form (HM-08-003), the tool MUST exit non-zero, write no file and no comment, and name the accepted forms in its error, with the ISSUE-N spelling of any number the source carries.

A fixed vocabulary is what keeps a source from another numbering off an unrelated issue, and it only holds if every other source is refused. Naming the accepted forms, and ISSUE-4646 for TASK-4646, lets the caller fix the call at once. --from-file applies the same rule, so a hand-built entry cannot bypass it.
Depends on: HM-08-001
Uses definition from: HM-08-003
HM-08-009 MUST When an implementation or idea entry's --source ISSUE-N names no issue in CERTCC/Vultron, or names a pull request, append-history MUST exit non-zero and write no file and no comment.

ISSUE-N claims the record belongs on issue N. When there is no such issue the claim is wrong, so filing the entry would hide a mistyped number, and gh issue comment on a pull request would put the record on the wrong kind of item.
Depends on: HM-08-001

HTTP Protocol Requirements

HTTP protocol requirements for the Vultron API, covering status codes, headers, and content negotiation.

File ID: HTTP

Request Size Limits

ID Priority Requirement Related
HTTP-02-001 MUST The default maximum inbox request body size MUST be 1 MB.

An operating limit of this codebase, which other implementations may set differently. The answer to a body over the limit is HTTP 413, which HTTP itself defines (IE-03-003, HTTP-03-007).
Extends: IE-03-002

HTTP Status Codes

The status codes HTTP itself defines for each outcome, which Vultron inherits (foundation, http). Where HTTP leaves the choice open, as with 422 for a schema failure, the code is this codebase's choice and the spec is project.

ID Priority Requirement Related
HTTP-03-002 MUST The API MUST return 201 Created for successful resource creation.

HTTP says a server SHOULD answer 201 when a request creates a resource. Making that a MUST on this codebase's own REST routes is this codebase's choice, which other Vultron implementations need not share; no peer delivery depends on it. Contrast HTTP-01-001, a SHOULD made a MUST on the inbox, which every implementation's deliveries depend on and so is protocol (ADR-0134).
HTTP-03-009 MUST The API MUST return 422 Unprocessable Entity for schema validation failures.

Indicates the request was well-formed but failed semantic or schema validation. HTTP leaves the choice between 400 and 422 open, so the code is this codebase's choice, like the inbox's 422 (IE-07-002).

Response Headers

ID Priority Requirement Related
HTTP-04-002 MUST Endpoints returning JSON that is not an ActivityStreams document (e.g., health checks, error bodies, the datalayer dump) MUST use Content-Type: application/json.

ActivityStreams defines the media type for its own documents (HTTP-04-001), but not for other JSON. This codebase chooses the media type of its other JSON responses. A plain application/json tells a client not to read the body as an ActivityStreams document.

Correlation ID Propagation

Request-tracing headers are an operating choice of this codebase's server; other Vultron implementations may trace requests differently, so these specs are project.

ID Priority Requirement Related
HTTP-05-001 SHOULD API SHOULD accept X-Correlation-ID or X-Request-ID headers for request tracing

An operator traces one request through the logs of several actors and services. If the server reuses the caller's tracing id, the logs on both sides carry the same key, and the operator does not have to match them by time or content.
HTTP-05-002 SHOULD API SHOULD generate correlation ID from activity id field if header not provided

The activity id is already unique (ID-01-001), and the sender and the receiver both know it. A correlation id taken from it gives the logs of both sides the same key when no header supplies one.

Request Timeout Handling

A response-time target and how this server meets it are operating limits of this codebase, not rules every Vultron implementation must obey, so these specs are project.

ID Priority Requirement Related
HTTP-06-001 SHOULD Inbox endpoints SHOULD respond with HTTP headers within 100ms

Ensures responsive UX for ActivityPub federation
HTTP-06-002 SHOULD Processing exceeding 100ms SHOULD return HTTP 202 and queue for background processing

Work that does not fit the response target (HTTP-06-001) is done after the answer. The sender then gets its answer at once and does not time out and send again, while the work still finishes in the background.
HTTP-06-003 SHOULD Timeout occurrences SHOULD be logged at WARNING level

A timeout is recoverable, but it shows that the server is too slow or that a peer cannot be reached. WARNING is the level for a recoverable anomaly (SL-03-001), so an operator sees timeouts without treating them as failures.

Rate Limiting Headers

Which rate-limit and retry headers this server sends is this codebase's HTTP choice. HTTP lets a server send Retry-After on a 429 or 503 but does not require it; making it a MUST here binds this server alone, so these specs are project.

ID Priority Requirement Related
HTTP-07-001 MAY API MAY include X-RateLimit-Limit header (maximum requests per window)

The limit lets a client pace its requests before it gets a 429. No peer relies on the header, and HTTP does not define it, so the server may omit it.
HTTP-07-002 MAY API MAY include X-RateLimit-Remaining header (requests remaining)

The number of requests left lets a client slow down before it reaches the limit and gets a 429. No peer relies on the header, so the server may omit it.
HTTP-07-003 MAY API MAY include X-RateLimit-Reset header (UTC timestamp for window reset)

The reset time tells a client when it can send at the full rate again, so it does not have to guess. No peer relies on the header, so the server may omit it.
HTTP-07-004 MUST A response with status 429 Too Many Requests or 503 Service Unavailable MUST include a Retry-After header indicating when the client should retry

Without Retry-After, a client has to guess when to try again. A client that tries again at once adds load to a server that is already overloaded or limited, and a client that waits too long delays its work. A stated time tells the client how long to wait.

FastAPI Response Serialization

ID Priority Requirement Related
HTTP-08-001 MUST API responses MUST include all fields of the actual returned object type, not only fields declared on the annotated base class

A route can return a subclass of the class its annotation names. If the response keeps only the fields of the annotated class, the client gets an incomplete object and no error shows the loss (HTTP-09).

AS2 Response Class Convention

ID Priority Requirement Related
HTTP-09-001 MUST A Vultron HTTP endpoint MUST answer with the AS2 form of the object model's own class, such as VulnerabilityCase, never with a separate response-model class.

Vultron is an AS2-over-HTTP protocol, and every substantive response body is an ActivityStreams object. The core classes are the object model and AS2 is their serialization (ARCH-25-001): their by_alias dump already has the camelCase names, @context and type, and an as_* name of a domain type is the same class (ARCH-25-003). A second response class would copy that shape and drift from it.
HTTP-09-002 MUST A FastAPI route handler that returns an AS2 object MUST return an AS2JSONResponse instance, from vultron/adapters/driving/fastapi/responses.py. It does not return a raw model_dump() dict, a plain JSONResponse or the bare wire model object.

Returning a Response subclass bypasses FastAPI's response_model filtering while preserving its use for OpenAPI schema generation (per FastAPI docs). This eliminates the subtype-field-stripping bug (HTTP-08-001) and ensures consistent Content-Type: application/activity+json across all AS2 endpoints.
HTTP-09-003 MUST AS2JSONResponse MUST serialize using model_dump(mode="json", by_alias=True, exclude_none=True) and set Content-Type: application/activity+json.

ActivityStreams uses camelCase property names, so the response uses the aliases. JSON mode makes values such as datetimes and URIs into strings. A field whose value is None stays out of the body and is not sent as null, which a consumer can read as a value. The media type is the one HTTP-04-001 requires for ActivityStreams documents.

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-005 MUST NOT The inbox endpoint MUST NOT serve any method but POST, including the read (GET) that ActivityPub allows an inbox's authenticated owner.

ActivityPub lets the actor that owns an inbox read it with an authenticated GET. This codebase has no authentication, so a GET on the inbox would show one actor's received activities to any caller. It serves no GET. An implementation that has authentication may serve the owner's read. Any other method gets the 405 that HTTP defines (IE-02-003). The POST delivery itself is the ActivityPub rule in IE-02-002.
Extends: IE-02-002

Request Handling

ID Priority Requirement Related
IE-03-002 MUST The endpoint MUST enforce a configurable maximum request body size.

Without a limit, any peer can send a body large enough to use up the receiver's memory or time. Deployments differ in the size they need, so the operator sets the limit in configuration.
IE-03-004 MUST The default maximum request body size MUST be documented in the deployment configuration reference.

Operators need to know the default limit to tune it for their deployment environment.
Extends: IE-03-002

Activity Validation

ID Priority Requirement Related
IE-04-002 MUST The endpoint MUST return HTTP 422 for validation failures

A sender needs to tell a body that is not valid JSON from a body that is valid JSON but not a valid activity. HTTP 400 answers the first (IE-07-001). A separate 422 tells the sender that the fault is in the content, so a resend of the same body cannot succeed.
Refines: HTTP-03-009

Response Timing

ID Priority Requirement Related
IE-05-001 MUST The endpoint MUST return HTTP 202 within 100ms

A sender waits for the answer to each delivery. A sender that waits too long can time out and send the activity again, which makes duplicates (ID-02). A fast 202 keeps senders moving and keeps redeliveries rare. The 100 ms figure is the response target of HTTP-06-001.
Refines: HTTP-06-001
IE-05-002 MUST NOT The endpoint MUST NOT block on handler execution

Handler work can take a long time: tree execution, DataLayer writes and outbox delivery. If the answer waited for that work, the sender could time out and send again, and one slow activity would hold the connection open. The inbox answers 202 first and processes the activity after the answer.

Asynchronous Processing

ID Priority Requirement Related
IE-06-001 MUST The endpoint MUST queue activities for background processing

Queuing the activity for background processing is what lets the endpoint answer before it processes the activity (IE-05-002). The activity is still processed, but after the answer and outside the request.
IE-06-002 MUST Background processing MUST be isolated from HTTP request/response cycle

The answer to the delivery is already sent when processing starts. A fault or a slow step in processing must not change that answer or keep the request open. The receiver tells the sender about the result of processing with protocol replies to the sender's inbox, not with the HTTP status.
IE-06-003 MUST NOT The inbox background task MUST NOT execute the synchronous BT pipeline (process_payload, including the pending-queue replay loop) on the ASGI event loop.

Starlette runs an async background task on the event loop itself, and the inbox pipeline is synchronous: tree execution, the tree lock and SQLite I/O. On the event loop, the whole process stops for each inbound activity, so the isolation of IE-06-002 holds only for the request that scheduled it. The outbox monitor then waits for each tree to finish, and a trigger route that waits for the tree lock can wait until its client times out.
Refines: IE-06-002
Constrains: IE-06-006
IE-06-007 MUST The inbox background task MUST run the synchronous BT pipeline in a worker thread, as the synchronous trigger routes do.

Off the event loop, the process keeps working while one activity's handler runs. It accepts deliveries from peers, answers DataLayer and trigger requests, and drains its own outboxes. The per-actor lock is held across the move to the worker thread, so the per-actor order of BT-11-001 stays the same.
Implements: IE-06-003
IE-06-004 MUST This rule covers an item that the inbox background task (run_inbox_pipeline in vultron/adapters/driving/fastapi/inbox_orchestration/pipeline.py) replays from the receiving actor's inbox queue. When the item raises an exception other than VultronProtocolViolationError, the task MUST re-queue it for at most a bounded, configurable number of attempts.

Handler exceptions propagate to this boundary (DR-03-002). An exception other than a protocol violation may be transient or a deterministic bug, so an unbounded re-queue could loop forever. A failed act keeps nothing (ADR-0214), so a retry re-runs the whole act. A live delivery is not queued: its retry is the sender's resend (ASK-07-010).
Extends: IE-06-001
IE-06-008 MUST The inbox background task MUST move a replayed item that used its last attempt (IE-06-004) to a dead-letter store.

An item that fails every attempt must leave the queue, or each drain retries it again. The dead-letter store keeps the item and its last error, so an operator can find the cause.
Extends: IE-06-004
IE-06-009 MUST The inbox background task MUST catch an exception that a replayed item raises, and log it at ERROR with the item's activity_id and actor_id.

An exception that escapes the task ends the whole drain, so the items after it wait for the next one. The ERROR record is how an operator learns that a replayed item failed, and the two IDs find the item.
IE-06-010 MUST The inbox background task MUST drop a replayed item that raised VultronProtocolViolationError, as a permanent failure.

A protocol violation fails the same way every time, so a retry only repeats the failure.
Extends: IE-06-004
IE-06-011 MUST The inbox retry (IE-06-004) and dead letter (IE-06-008) MUST use the same persisted retry and dead-letter mechanism as outbox delivery (OX-13).

One mechanism keeps one set of rules for counts and dead letters. The outbox's persisted mechanism keeps counts across restarts, so a restart does not reset an item's attempts.
Implements: IE-06-004
Implements: IE-06-008
IE-06-005 MUST Each attempt to replay an item from the receiving actor's inbox queue MUST commit as one DataLayer transaction. The transaction covers taking the item's id off the queue, releasing the record that holds it for its replay, and the attempt itself. It also covers the attempt's settlement: the attempt count, the record held again, the id queued again, the dead letter and any held fault.

The held record is the only copy of a received activity the replay can rebuild it from (DL-06-006), and the sender is not answered while the item is retried (ASK-07-014), so an item lost between its dequeue and its settlement is never recovered. Writes that must land together share one transaction, never a repair pass (ADR-0146). The act's own transaction nests inside the attempt's, so a failed act still keeps nothing (ADR-0214).
Extends: IE-06-004
IE-06-012 MUST This rule covers a process stop during a replay attempt, and a raise that the drain does not settle as a failed attempt (IE-06-004). Either MUST leave the item queued and held, with the attempt count it had before the attempt began.

The attempt count bounds an activity's failures, not the store's. A raise that escapes the attempt rolls back the count with everything else, so it is not counted. An item whose settlement fails every time is retried by each drain until the store fault is fixed.
Derives from: IE-06-005
Uses definition from: IE-06-004
IE-06-013 MUST When an attempt raises an exception that the drain does not settle as a failed attempt (IE-06-004), the drain MUST end with that raise.

The raise is surfaced, not counted. The item stays queued (IE-06-012), so it waits for the next replay.
Extends: IE-06-004
IE-06-006 MUST When the serving process starts, it MUST replay every item queued in each hosted actor's inbox queue, with the same bounded retry and dead letter as a replay after a delivery (IE-06-004), under the same per-actor lock as that actor's inbox background task and off the ASGI event loop (IE-06-003).

Without it, an item that survived a stop (IE-06-005) is replayed only when the next delivery reaches the same actor, which may never happen. The outbox has the same safety net in its monitor (OX-09-002).
Extends: IE-06-004
IE-06-014 MUST When the serving process starts, it MUST run again, before the queue replay, every received record in holding that owes no replay. Each record is run as a delivery of the body it holds.

A process stop during a handling tree leaves the message's record in holding (CLP-10-074), and no queue item stands for it. Without this, only a resend from the sender finishes it, which may never happen. The re-run reads the record, so what the first run already did is not done again (CLP-10-080).
Extends: IE-06-006
Uses definition from: CLP-10-074
IE-06-015 MUST Each startup re-run of IE-06-014 MUST be counted against the inbox retry budget (IE-06-004) before it starts, and a record whose budget is spent is dead-lettered and not run again.

A message whose handling stops the process is left in holding again by every start. Counted only after a run, it would stop every start and the receiver could never come up. The count is stored before the re-run, outside its transaction, so a process stop is counted too.
Refines: IE-06-014
Uses definition from: IE-06-004

Error Responses

ID Priority Requirement Related
IE-07-002 MUST The endpoint MUST return HTTP 202 for a successfully accepted activity, HTTP 400 for an activity whose addressing provably excludes the receiving actor (IE-11-001), and HTTP 422 for an activity that fails schema validation.

These codes are this implementation's choices, not protocol rules. The protocol does not yet say which HTTP answers a receiving actor gives, so a peer cannot rely on them (see the open question on transport status codes). The codes that HTTP itself defines for transport failures are in IE-07-001.
Extends: IE-07-001
Uses definition from: IE-11-001

Response Format

ID Priority Requirement Related
IE-08-001 MUST The endpoint MUST answer an accepted activity with a 202 that carries no body.

The endpoint answers before it processes the activity (IE-05-001), so it knows nothing yet beyond acceptance. The sender already holds the activity's id, and the inbox has no read surface for a result (IE-02-003, IE-02-004): the sender learns the disposition from the replies delivered to its own inbox. A body on the 202 could only repeat what the sender sent, or claim a result that does not exist yet.
IE-08-002 MUST The endpoint MUST answer each refused activity with the error body of EH-05-001.

A refusal is the one answer that tells the sender something beyond acceptance: why its activity was not taken. One body shape for every refusal lets a sender read the reason without a parser for each status code.
Refines: EH-05-001

Logging

ID Priority Requirement Related
IE-09-001 MUST The endpoint MUST log all requests at INFO level

Each delivery is a normal protocol event (SL-03-001). An operator who traces a case across actors needs a record of each delivery that an actor received, also one that the actor refused later.

Idempotency

ID Priority Requirement Related
IE-10-001 SHOULD The endpoint SHOULD detect a redelivered activity early, at ingress: when the receiving actor already holds the activity under a key it derives from the activity id (its one ReceivedActivityRecord, whatever stage it is in), and the delivery's sealed body is exactly the body held for that id, the redelivered body is not held again, and the copy the receiver holds is routed in its place (VM-08-002). Whether that copy carries received evidence is decided by whether a replay is still owed from the held body: with one owed the copy carries none, because the held copy is not this delivery and will carry the evidence when it is replayed; with none owed the body the receiver holds is routed, carrying that body as its received evidence. A delivery under a held id whose body differs is not a redelivery; IE-10-002 refuses it.

Ingress is the first point where the receiver can read durable evidence of an earlier delivery, so the early filter that ID-05-002 permits goes there. The evidence is under a key the receiver derives, because a row under the sender's id reads as one of the receiver's own activities (DL-06-006). The held record is the received body (ADR-0149), so a resend of an activity held with no replay owed is parsed again from that body, and that body is its evidence. The received tree's seen-before door then answers it from the record's stage (CLP-10-010, ADR-0214): an archived act was applied, so the resend is a repeat; an act a run left in holding with no verdict, such as one whose consequence failed, runs again and records the held body (CLP-07-015, CLP-10-074). Only a resend of the same body is a redelivery, which is why ingress keeps the one comparison of bodies: if the receiver routed its held copy in place of a different body, that body would be lost with no trace (IE-10-002).
Refines: ID-05-002
Uses definition from: DL-06-006
Uses definition from: VM-08-002
Implements: ID-05-001
IE-10-002 MUST This rule covers a delivery whose activity id the receiving actor already holds (IE-10-001). The endpoint MUST refuse the delivery when its sealed received body (VM-08-002) is not exactly the body held for that id. The held body is the deferred record's while the first delivery is still deferred, else the body intake recorded. This applies to every activity type, including an Add(CaseLedgerEntry) that ingress hydrates in place (SYNC-13-004).

An activity id names one activity (ID-01-001). A second body under a held id is a sender bug or a changed version of what was said. The comparison uses the exact sealed text of each body (a SHA-256 digest), so no rule decides which differences count. The inbox answers 202 before it processes the activity (IE-05-002), so the refusal is the inbox outcome, not an HTTP status. The already-stored gate (SYNC-12-003) still answers a same-body repeat of an Add(CaseLedgerEntry).
Extends: IE-10-001
Uses definition from: VM-08-002
See also: SYNC-13-004 — context for the reader
IE-10-003 MUST NOT The endpoint MUST NOT route a delivery that IE-10-002 refuses, or the held copy in its place.

Routing the held copy in place of the refused body hides the change that the sender made. Routing the refused body acts on a second meaning for one id.
Extends: IE-10-002
IE-10-004 MUST NOT The endpoint MUST NOT write or change anything in the receiving actor's store for a delivery that IE-10-002 refuses. The first delivery's record stays as it was.

The inbox refuses the body and does not quarantine it. A write for the refused body would change the record of the first delivery, which is the only record of what the sender said first.
Extends: IE-10-002
IE-10-005 MUST The endpoint MUST log the refusal of IE-10-002 at WARNING with the activity id and the sending actor.

The inbox does not keep the refused body, so the WARNING is the only trace of it. The two IDs let an operator find the sender and the held activity.
Extends: IE-10-002

Inbox Orchestration

Testable requirements for the core BT-backed inbox orchestration module, covering the InboxOutcome model, BT sequence invariants, adapter injection rules, caller interface constraints, and error/outcome behavior.

File ID: IO

InboxOutcome Model

ID Priority Requirement Related
IO-01-001 MUST The inbox orchestration module MUST define an InboxOutcome Pydantic model as the sole return type of process_payload.

A typed return model makes outcome inspection safe and self-documenting for all callers (FastAPI, CLI, tests).
IO-01-002 MUST InboxOutcome MUST include a status field typed as the InboxOutcomeStatus StrEnum, whose members are processed, deferred, and rejected.

Three statuses cover the outcome space: dispatched, held for replay, and not processable. Deferred has two producers, the pre-dispatch defer check (case not yet known) and a handler returning DEFERRED, and both keep working.
IO-01-006 MUST When dispatch ran, the inbox pipeline MUST derive InboxOutcome's status from the handler's HandlerResult disposition (UCORG-05-017), not from dispatch merely not raising. APPLIED and SKIPPED yield processed, DEFERRED yields deferred, and REFUSED yields rejected.

A dispatch that does not raise can still be a refusal, so the status must come from the handler's own verdict. The mapping lives only in the pipeline's dispatch node, so handlers never name this vocabulary (HP-01-004). A dispatch where no handler ran is never processed (UCORG-05-012). DeferCheckNode and DereferenceCheckNode (AKM-05-010) also defer, before dispatch. Only a handler's DEFERRED goes through this mapping.
Uses definition from: IO-01-002
Uses definition from: UCORG-05-017
IO-01-003 MUST InboxOutcome MUST include a context_id field (nullable string) carrying the case or activity context identifier, when available.

Callers need context identity for logging, telemetry, and pending-queue management.
IO-01-004 MUST InboxOutcome MUST include a failure_reason field (nullable string) that carries a human-readable explanation when the status is rejected or deferred.

Explicit failure reasons support triage without log scraping.
IO-01-007 MUST When a handler returns REFUSED, the inbox pipeline MUST set InboxOutcome's failure_reason to the handler's HandlerResult reason.

A REFUSED HandlerResult always carries a reason (ADR-0095). When the outcome carries that reason, every handler refusal is explained.
Refines: IO-01-004
IO-01-005 MUST InboxOutcome MUST include an unhandled field (boolean, default false). The field is true only for a rejected outcome whose semantic type no use case handles ("no use case found", SE-05-002).

A receiver that does not handle a message has not found the message invalid (ADR-0140 item 5). The flag lets a caller tell that outcome from other rejections. The flag is set from the dispatcher's own verdict, not read from the reason text.
Uses definition from: SE-05-002
IO-01-008 MUST The driving adapter MUST log an unhandled outcome (IO-01-005) at INFO, not at the WARNING it uses for other rejections (UCORG-05-013).

A recognized but unhandled activity is a normal operation, not a recoverable anomaly (SL-03-001). A WARNING for it would hide the real anomalies among routine records.
Refines: UCORG-05-013
Uses definition from: IO-01-005

BT Orchestration Module

ID Priority Requirement Related
IO-02-001 MUST The inbox orchestration module MUST be located at vultron/core/behaviors/inbox/.

Placement in core/ satisfies the hexagonal architecture constraint that core imports no framework (ARCH-01-001, ADR-0009) and enables the module to be used by FastAPI, CLI, and test adapters equally.
IO-02-001b MUST NOT The inbox orchestration module MUST NOT import from vultron/adapters/ or any web framework package.

Core holds the inbox policy so that every driving adapter and every test uses the same policy. An import from vultron/adapters/ or a web framework binds core to one adapter. A test or a second adapter then cannot run the policy without that adapter (ARCH-01-001).
Refines: ARCH-01-001
IO-02-002 MUST The BT implementation MUST enforce the following fixed node ordering via BT Sequence nodes: (1) parse inbound payload, (2) rehydrate Activity, (3) extract MessageSemantics, (4) defer-eligibility check, (5) dispatch to use-case path, (6) build typed outcome.

Fixed BT ordering makes the inbound pipeline auditable and prevents callers from accidentally invoking steps out of order.
IO-02-003 MUST The process_payload function MUST be the sole caller-facing entry point of the inbox orchestration module.

Encapsulating intermediate steps preserves depth and prevents shallow reimplementations of parts of the pipeline.
IO-02-003b MUST NOT Intermediate behavior-tree nodes used internally by process_payload MUST NOT be exported as public API symbols.

If the internal nodes are public, a caller can run some steps of the pipeline and skip others, such as the defer check or the outcome step. Only process_payload runs every step in its fixed order (IO-02-002), so only it is public.
Refines: IO-02-003
IO-02-004 MUST NOT The inbox orchestration module MUST NOT instantiate or call a use-case class directly inside a behavior-tree node update() method.

Use cases create BTs; BT nodes are leaves. Calling a use case from a node creates a prohibited BT-UseCase-BT chain (BT-06-006).

Adapter Injection

ID Priority Requirement Related
IO-03-001 MUST process_payload MUST accept exactly two injected adapters: an ingress payload adapter (raw input to as_Activity) and a dispatch adapter (VultronEvent to use-case execution).

Two adapters with clear names make the two required inputs of the pipeline explicit. Each additional adapter is one more interface for every caller to supply and for the module to hide.
IO-03-005 MUST The dispatch adapter (IO-03-001) MUST return the handler's HandlerResult (UCORG-05-010), which is the only channel by which the verdict reaches InboxOutcome.

The dispatch adapter returns the HandlerResult, so a handler does not have to write the verdict to a blackboard key. InboxOutcome's vocabulary stays out of handlers (HP-01-004).
Refines: UCORG-05-010
Extends: IO-03-001
IO-03-002 MUST Pending-queue management MUST be provided to the inbox orchestration module via an injected port dependency.

Injecting the pending-queue port keeps core/ free of adapter dependencies and aligns with hexagonal architecture.
IO-03-002b MUST NOT The inbox orchestration module MUST NOT access pending-queue storage directly from vultron/adapters/.

Pending-queue storage is an adapter detail. If the inbox orchestration module reads that storage directly, it depends on an adapter, against ARCH-01-001, and a test cannot give it a different queue. In this module, the injected port (IO-03-002) is the only path to the queue.
Refines: IO-03-002
IO-03-003 MUST The FastAPI inbox path MUST supply adapter implementations to process_payload at construction time.

Policy logic in the router binds it to the web framework, against the hexagonal layering that keeps policy in a framework-free core (ARCH-01-001, ADR-0009), and makes the orchestration untestable without a running FastAPI app.
IO-03-003b MUST NOT The FastAPI inbox path MUST NOT contain inbox policy logic, apart from the synchronous guard that IO-03-007 allows.

Policy in the router binds it to the web framework, against the hexagonal layering that keeps policy in a framework-free core (ARCH-01-001, ADR-0009). It also makes the orchestration untestable without a running FastAPI app.
Refines: IO-03-006
See also: IO-03-007 — context for the reader
IO-03-006 MUST All inbox policy logic MUST reside in the core inbox orchestration module, apart from the synchronous guard that IO-03-007 allows.

One home for inbox policy lets a test drive all of it without a web framework, and keeps the core free of framework code (ARCH-01-001, ADR-0009).
IO-03-007 MAY A synchronous guard MAY live at the route level when synchronous refusal is required (IE-11-001, ADR-0068). Such a guard refuses an inbound Activity before the HTTP 202 is returned and before the background task is scheduled.

Such a guard must act before the background task is scheduled, so it must sit at the route. ADR-0068 documents this tradeoff.
Supersedes: IO-03-006
See also: IE-11-001 — context for the reader
IO-03-004 MUST NOT The ingress payload adapter MUST NOT write an inline object of a received activity to the receiver's DataLayer as a record readable by its id. This holds on receipt and for a deferred replay.

A stored inline object is the receiver's own record of that object. A stored case is the receiver's replica, so if the receiver stores a case at receipt, a sender's snapshot can name the sender as CASE_MANAGER and pass the trust check that must refuse it (PCR-03-004, CBT-01-011). A handler therefore sees the receiver's record of any id it holds, never the carried copy, so a guard keys on the stored record (HP-08-006).
IO-03-008 MAY To rebuild the routed activity, the ingress payload adapter MAY stage the inline objects in a holding area outside the receiving actor's DataLayer. The holding area answers a read only when the DataLayer holds nothing under the id, and keeps nothing past the delivery.

Routing still needs the inline object, because the rebuilt activity names it by id, and a bare id matches no pattern (SE-01-006). The receiver's record wins over the carried copy, so a carried case cannot replace the replica that the receiver rebuilds from the ledger.
Implements: IO-03-004
IO-03-009 MAY For an activity the inbox defers, the ingress payload adapter MAY keep the activity itself, as the received body the parser sealed (VM-08-002). It keeps the body beside the staged rows on the activity's one record, keyed by the activity and marked as owing a replay, which the replay or the queue's expiry releases. The record goes with the release, because a message still owed a replay has not been archived (ADR-0214). The activity names there the case it waits on, so what waits for a case is read from the waiting activities and kept in no second list. A held out-of-order Add(CaseLedgerEntry) (SYNC-14-001) is kept the same way, released by its replay or by the holding area's bound (SYNC-14-006).

The record holds the activity too, because no copy under its sender's id is there to replay (DL-06-006). One record per message, rather than a holding record beside an archive, is what lets the receiver answer "have I seen this?" with one read, and keeps a queued id from outliving the body behind it (ADR-0214).
Implements: IO-03-004
Uses definition from: VM-08-002
Uses definition from: SYNC-14-001
Uses definition from: SYNC-14-006

Caller Interface

ID Priority Requirement Related
IO-04-001 MUST process_payload MUST always return an InboxOutcome instance, regardless of payload validity.

Typed outcomes allow callers to handle all cases uniformly without exception-driven control flow at the integration boundary.
IO-04-001b MUST NOT process_payload MUST NOT raise an exception for a protocol-invalid payload.

The FastAPI inbox background task, the inbox queue drain (which also replays deferred activities) and the tests all call process_payload. If a protocol-invalid payload raises, each caller needs its own handler for the raise, and a caller that has none loses the outcome.
Refines: IO-04-001
IO-04-004 MUST process_payload MUST encode every error condition in the InboxOutcome it returns.

An outcome value gives every caller the same result for every payload, so no caller has to read logs or catch a raise to learn what failed.
Implements: IO-04-001b
IO-04-002 MUST Tests for process_payload MUST assert on InboxOutcome.status and InboxOutcome.failure_reason fields.

Interface-level test assertions are resilient to internal refactors and validate the contract rather than the implementation.
IO-04-002b MUST NOT Tests for process_payload MUST NOT patch internal behavior-tree node helper methods to verify pipeline behavior.

A test that patches a node helper checks the internal structure, not the behavior of the pipeline. It passes when the pipeline is wrong and fails when a correct change moves the helper. The outcome fields (IO-04-002) are what callers rely on.
Extends: IO-04-002
IO-04-003 SHOULD Both a production ASGI adapter and an in-memory test adapter SHOULD implement the ingress payload adapter interface, so that the same process_payload seam is used in both runtime and test contexts.

Shared interface across runtime and test adapters validates real-world behavior and reduces adapter-specific test scaffolding.

Inbox Pipeline

Requirements for InboxPipeline, an injectable class that exposes the full rehydrate, prepare-for-dispatch, and dispatch-or-defer chain as a single testable unit. Honours the existing ActivityDispatcher and DataLayer ports so that tests can drive the real pipeline with in-memory adapters.

File ID: IBP

InboxPipeline Class Contract

ID Priority Requirement Related
IBP-01-001 MUST InboxPipeline MUST accept an ActivityDispatcher and a DataLayer as constructor parameters and store them as private attributes.

Injection via constructor makes the pipeline testable with any compliant adapter pair — including in-memory test doubles — without monkeypatching module-level globals.
IBP-01-002 MUST InboxPipeline.process(activity_id: str) MUST execute the full inbox processing chain: rehydrate the activity from the DataLayer, extract the domain event, check case context, defer to the wait queue or dispatch via the activity dispatcher, and handle errors with requeue logic.

Wrapping the full rehydrate-to-dispatch path (not the simpler handle_inbox_item) ensures that deferral and error-requeue behaviours are exercisable in unit tests.
IBP-01-003 MUST InboxPipeline.process() MUST return the VultronEvent when the activity was dispatched.

A routing-safety-net test reads the returned event to see which semantic type the pipeline dispatched, without having to inspect DataLayer side effects.
IBP-01-005 MUST InboxPipeline.process() MUST return None when the activity was deferred or an error prevented dispatch.

A None return is an unambiguous signal to routing-safety-net tests that dispatch did not occur, without requiring the test to inspect DataLayer side effects.
Extends: IBP-01-003
IBP-01-004 MUST NOT InboxPipeline MUST NOT replace or modify the module-level _DISPATCHER_SLOT or the init_dispatcher() / dispatch() functions in inbox_handler.py.

The pipeline is a parallel path; the existing lifespan wiring remains the canonical production entry point.

Factory Functions

ID Priority Requirement Related
IBP-02-001 MUST A build_test_pipeline(dl: DataLayer) -> InboxPipeline module-level factory function MUST be provided in the same module as InboxPipeline.

A named factory hides DirectActivityDispatcher construction, use_case_map() lookup, and port-factory wiring so that tests remain focused on behaviour rather than plumbing.
IBP-02-002 MUST build_test_pipeline() MUST construct a DirectActivityDispatcher with the real use_case_map() and the same port factories that make_dispatcher() uses in production.

Using production wiring guarantees that routing-safety-net tests fail immediately when a SEMANTIC_REGISTRY use-case registration is missing or a use-case constructor signature drifts.
IBP-02-003 SHOULD A pytest fixture named test_pipeline SHOULD be provided in a conftest.py file in the test directory that exercises InboxPipeline, yielding a (InboxPipeline, DataLayer) tuple backed by an in-memory SqliteDataLayer("sqlite:///:memory:").

A shared fixture eliminates per-test boilerplate and ensures every routing-safety-net test starts with an identical, isolated DataLayer.

Module Location

ID Priority Requirement Related
IBP-03-001 MUST InboxPipeline and build_test_pipeline() MUST be defined in vultron/adapters/driving/fastapi/inbox_pipeline.py.

Co-locating the pipeline with inbox_handler.py makes the seam explicit and avoids introducing a new adapter layer just for testability.
IBP-03-002 MUST NOT inbox_pipeline.py MUST NOT import from inbox_handler.py's private helpers (such as _DISPATCHER_SLOT) by name as module-level globals.

The pipeline MUST call the helpers as functions, not bind to their module-level identities, so that future refactoring of inbox_handler.py does not silently break the pipeline.

Routing-Safety-Net Test Coverage

ID Priority Requirement Related
IBP-04-001 MUST At least one routing-safety-net test MUST exist per semantic domain (report, case, embargo, note, actor, status, sync) asserting that the correct use case fires and produces the expected DataLayer side effect.

Per-domain coverage catches SEMANTIC_REGISTRY use-case registration gaps immediately without requiring exhaustive per-enum-value tests.
IBP-04-002 MUST A routing-safety-net test MUST use build_test_pipeline() (real wiring).

The real wiring is what the safety net exists to exercise. A test that builds its own pipeline can miss a wiring defect that production has.
IBP-04-005 MUST NOT A routing-safety-net test MUST NOT mock _DISPATCHER_SLOT, prepare_for_dispatch, or use_case_map().

Mocking the exact symbols the test is supposed to exercise defeats the purpose of a routing safety net.
Extends: IBP-04-002
IBP-04-003 MUST Tests that exercise the deferral path MUST assert that process() returns None and that the activity ID appears in the pending-case inbox after the call.

A deferred activity is processed later, when its case exists. A test that checks only that dispatch did not occur cannot tell a correct deferral from an activity that was lost. The activity id in the pending-case inbox shows that the pipeline kept the activity for replay.
IBP-04-004 SHOULD Routing-safety-net tests SHOULD be placed in test/adapters/driving/fastapi/test_inbox_pipeline.py.

One file for the safety net lets a reader find every routing check in one place, and lets a change to the pipeline run them together.
IBP-04-006 SHOULD NOT Routing-safety-net tests SHOULD NOT require the @pytest.mark.integration marker, since they use only in-memory adapters.

Keeping these tests in the unit suite ensures they run on every local pytest invocation, providing fast feedback without needing the full integration environment.

Lifecycle-Staged Domain Types

Rules for lifecycle-staged domain types anchored on guaranteed-field changes. A lifecycle milestone earns a distinct staged type only when it changes the set of required (non-None) fields; milestones that only gate permitted actions are modeled as predicates and preconditions rather than new types.

File ID: LST

Field-Set Governing Principle

ID Priority Requirement Related
LST-01-001 MUST A lifecycle milestone MUST be modeled as a distinct staged type only when it changes the set of guaranteed (required, non-None) fields on the domain object.

A subtype whose field set is identical to its parent's adds type ceremony without a type-checker payoff and invites combinatorial proliferation. See ADR-0033.
LST-01-002 MUST A milestone that only changes which actions are permitted, without changing which fields are present, MUST be modeled in the transition model and precondition specs, not as a distinct type.

Action-gating is a precondition on transitions, not a change in data shape. See ADR-0033 and LST-05.

VulnerabilityCase Staged Types

ID Priority Requirement Related
LST-02-001 MUST The VulnerabilityCase staged family MUST consist of exactly three types: IncomingReport (report data, no case), Case (a case exists), and EmbargoedCase (an embargo is active), because only these boundaries change the guaranteed-field set.

Case existence and embargo-active each add a guaranteed field; no other case-universal milestone does. See ADR-0033.
LST-02-002 MUST A Case MUST guarantee at least one vulnerability report, the reporter and receiver participants (at least two parties), and a seeded case_statuses list.

ADR-0041 (superseding ADR-0015) requires the CASE_MANAGER to author all initialization entries when accepting a CaseProposal, so these structural minimums are guaranteed for any case that exists.
Refines: ARCH-10-001
LST-02-003 MUST An EmbargoedCase MUST guarantee active_embargo is non-None and em_state is in {ACTIVE, REVISE}.

The EM machine never returns to NONE/PROPOSED once ACTIVE, so this is a monotonic milestone with a genuine type-level non-None guarantee.
LST-02-004 MUST NOT Per-participant RM state (valid, accepted, deferred) MUST NOT be modeled as a VulnerabilityCase staged type.

RM state is per-participant, not case-universal; a case-level RM type is ill-defined ("valid according to whom?"). See LST-04.

No Subtypes for Status Objects

ID Priority Requirement Related
LST-03-001 MUST NOT ParticipantStatus and CaseStatus MUST NOT be given lifecycle-staged subtypes, because no RM/vfd/EM/pxa milestone adds a field to them.

Their state fields are always-present enums; milestones change values, not the field set. Per LST-01-001 they earn no type. See ADR-0033.

Ratchets as Predicates and State Groups

ID Priority Requirement Related
LST-04-001 MUST Per-participant RM and vfd ratchets, and case-level EM and pxa ratchets, MUST be modeled as state-group tuples and is_*() predicates, extending the existing RM_ACTIVE / EM_NEGOTIATING / is_rm_at_least() helpers in vultron/core/states/.

These milestones are monotonic value transitions without field-set changes; predicates give ergonomic checks without a subtype. See ADR-0033.

Read-Boundary Promotion and Transition Model

ID Priority Requirement Related
LST-05-001 MUST A core function requiring a narrowed staged type MUST obtain it by validating the generic object at its entry boundary (e.g. EmbargoedCase.model_validate(case)), which narrows on success and raises immediately on invariant violation.

Applies ADR-0032's validate-at-the-edge pattern at the DataLayer read boundary; the subtype's own validator is the promotion logic.
LST-05-002 MUST NOT The lifecycle stage MUST NOT be stored as a persisted field on any domain object.

A stored stage can drift from the underlying invariants, creating two sources of truth. See ADR-0033 transition model.
LST-05-002b MUST The staged type MUST always be re-derived from the base case data at read time; the base case data is the single source of truth for stage determination.

A case's stage changes whenever its fields change, for example when an embargo ends, so a stage decided at an earlier read can claim guarantees the current data does not meet. Re-deriving from the data on every read means a caller cannot act on an EmbargoedCase whose embargo is gone.
Extends: LST-05-002
LST-05-003 MUST Staged types MUST remain round-trippable through the DataLayer: a persisted staged object rehydrates to the base type and re-validates to its staged type without loss.

Rehydration always yields a valid object; the staged-type guarantee must survive persistence. See ADR-0033.

Protocol Shorthand to MessageSemantics Mapping

Authoritative normative bridge from protocol message shorthand labels (RS, EP, CV, etc.) used in behavioral conformance specs to their MessageSemantics enum values and corresponding AS2 wire-format specifications. Each entry provides one row in the three-hop chain: shorthand to MessageSemantics enum value to AS2 wire form. The correspondence is many-to-many in both directions: several shorthands may collapse onto one wire activity (CV/CF onto vfState, CP/CX/CA onto pxaState, EV onto EP), and one shorthand may expand across several wire activities (GI, ER). Shorthands with no dedicated dispatch value are the protocol-layer error and acknowledgment signals; these are not unimplemented — the purposes they name are served by mechanisms partitioned on a different axis, specified normatively in MSM-05.

File ID: MSM

RM Protocol Message Shorthands

Normative shorthand-to-semantic mappings for Report Management (RM) protocol messages, covering RS, RI, RV, RD, RA, RC, RE, and RK.

ID Priority Requirement Related
MSM-01-007 MUST Protocol shorthand RE (Report Management Error) has no dedicated MessageSemantics dispatch value and no entry in SEMANTIC_REGISTRY; report-management error conditions MUST instead be reported through the failure-mode mechanisms specified in MSM-05-001.

RE names an error condition scoped to report management. The implementation does not partition faults by state machine, so there is no RE-shaped wire form; it partitions by failure mode instead — not understood, declined, or needing explanation (MSM-05-001). Read this entry as "mapped onto a different axis", not as "unimplemented".
Refines: MSM-05-001

EM Protocol Message Shorthands

Normative shorthand-to-semantic mappings for Embargo Management (EM) protocol messages, covering EP, EA, EV, EJ, EC, ER, ET, EE, and EK. The formal message set models the case's view of the embargo, so an acceptance or rejection shorthand names the Case Owner's decision that makes its EM transition, not each Participant's answer to the Invite. Embargo revision shorthands (EV, EJ, EC) share wire formats with their initial-proposal counterparts (EP, ER, EA); the distinction is contextual rather than structural.

ID Priority Requirement Related
MSM-02-003 MUST Protocol shorthand EV (Embargo Revision Proposed) MUST dispatch as MessageSemantics.INVITE_TO_EMBARGO_ON_CASE; its AS2 wire form is Invite(EmbargoEvent)[target=Actor, context=VulnerabilityCase] per VAM-05-005 — identical to EP. The revision context is inferred from the presence of an active embargo.

EV, EJ, and EC are aliases for EP, ER, and EA at the wire layer (vultron/bt/messaging/states.py). The distinction between initial proposal and revision proposal is not encoded in the AS2 activity structure; implementations MUST infer it from local EM state.
Uses definition from: VAM-05-005
MSM-02-008 MUST Protocol shorthand EE (Embargo Management Error) has no dedicated MessageSemantics dispatch value and no entry in SEMANTIC_REGISTRY; embargo-management error conditions MUST instead be reported through the failure-mode mechanisms specified in MSM-05-001.

Symmetric with MSM-01-007 (RE): faults are partitioned by failure mode rather than by state machine, so no embargo-scoped error wire form exists.
Refines: MSM-05-001
MSM-02-009 MUST Protocol shorthand EK (Embargo Management Acknowledgment) has no dedicated MessageSemantics dispatch value and no entry in SEMANTIC_REGISTRY; acknowledgement of embargo state carried on the case ledger MUST instead follow the cumulative hash-chain mechanism specified in MSM-05-002.

Per-message positive acknowledgement is redundant for ledger-replicated state: a matching prev_log_hash already proves receipt of every prior entry (MSM-05-002).
Refines: MSM-05-002

CS Protocol Message Shorthands

Normative shorthand-to-semantic mappings for CVD Case State (CS) protocol messages, covering CV, CF, CD, CP, CX, CA, CE, and CK. CS status shorthands are split across two semantics by dimension scope, because the CS hypercube mixes participant-scoped and case-scoped dimensions: the participant-scoped V/F/D dimensions (CV, CF, CD) dispatch as ADD_PARTICIPANT_STATUS_TO_PARTICIPANT and are encoded in the ParticipantStatus payload, while the case-scoped P/X/A dimensions (CP, CX, CA) dispatch as ADD_CASE_STATUS_TO_CASE and are encoded in the CaseStatus payload. There are no case-level V/F/D states (ADR-0075). In both groups the specific state transition is encoded in the object payload rather than in the activity type.

ID Priority Requirement Related
MSM-03-007 MUST Protocol shorthand CE (Case State Error) has no dedicated MessageSemantics dispatch value and no entry in SEMANTIC_REGISTRY; case-state error conditions MUST instead be reported through the failure-mode mechanisms specified in MSM-05-001.

Symmetric with MSM-01-007 (RE): faults are partitioned by failure mode rather than by state machine, so no case-state-scoped error wire form exists.
Refines: MSM-05-001
MSM-03-008 MUST Protocol shorthand CK (Case State Acknowledgment) has no dedicated MessageSemantics dispatch value and no entry in SEMANTIC_REGISTRY; acknowledgement of case-state changes carried on the case ledger MUST instead follow the cumulative hash-chain mechanism specified in MSM-05-002.

Symmetric with MSM-02-009 (EK): case-state changes are ledger-replicated, so hash-chain continuity already acknowledges them cumulatively and a per-message ack would be redundant.
Refines: MSM-05-002

General Protocol Message Shorthands

Normative shorthand-to-semantic mappings for General (non-state-machine) protocol messages, covering GI, GK, and GE. Unlike the RM, EM, and CS groups, the General shorthands map to wire activities by expansion: a single shorthand covers several distinct wire activities rather than collapsing several shorthands into one.

ID Priority Requirement Related
MSM-04-001 MUST The note lifecycle MUST realize protocol shorthand GI (General Inquiry) as MessageSemantics.ADD_NOTE_TO_CASE and MessageSemantics.REMOVE_NOTE_FROM_CASE. Their AS2 wire forms are Add(Note)[target=VulnerabilityCase] (VAM-07-002) and Remove(Note)[origin=VulnerabilityCase] (VAM-07-003). A received Create(Note) is not a protocol message (VAM-01-019). These are not the whole of GI: MSM-04-002 adds the actor-suggestion exchange.

GI is defined in the formal protocol as any message conveying non-state-change information, so it is inherently one-to-many on the wire. The Add and Remove split is a wire-layer artifact with no formal counterpart: the formal set models the inquiry, not the object lifecycle that carries it.
Uses definition from: VAM-07-002
Uses definition from: VAM-07-003
See also: VAM-01-019 — scope boundary: the Create(Note) clause; realizing GI does not follow from it
MSM-04-002 MUST Protocol shorthand GI MUST additionally cover the actor-suggestion exchange, dispatching as MessageSemantics.OFFER_ACTOR_TO_CASE, MessageSemantics.OFFER_CASE_PARTICIPANT, MessageSemantics.ACCEPT_OFFER_CASE_PARTICIPANT, MessageSemantics.REJECT_OFFER_CASE_PARTICIPANT, MessageSemantics.ACCEPT_ACTOR_RECOMMENDATION, or MessageSemantics.REJECT_ACTOR_RECOMMENDATION.

messages.md lists "suggesting a potential Participant to be added to a case" among its GI examples, so actor suggestion is a GI expansion and MUST NOT be classified as case management. What the formal set models as one inquiry the implementation realizes as a multi-hop negotiation with its own accept and reject responses.
Extends: MSM-04-001
MSM-04-003 MUST Protocol shorthands GK (General Acknowledgement) and GE (General Error) MUST NOT be assigned dedicated MessageSemantics dispatch values; the purposes they name are served by the mechanisms specified in MSM-05.

Recording these as plain absences invites the reading that the behaviour is unimplemented. It is implemented, on a different axis — see MSM-05-001 and MSM-05-002.
Refines: MSM-05-001
Refines: MSM-05-002

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

Activity Structure Validation

ID Priority Requirement Related
MV-01-005 MUST The semantic-dispatch stage — the type lookup that runs after parse_activity has already accepted the activity against the AS2 vocabulary — MUST handle missing or null fields without raising unhandled exceptions.

An activity can pass the vocabulary check and still omit a field that the patterns read. If a lookup of a missing field raises an exception, one incomplete message causes a dispatch failure. The message then does not get the semantic type UNKNOWN.
MV-01-006 MUST The semantic-dispatch stage MUST treat an activity whose type matches no entry in the semantic pattern registry (SEMANTIC_REGISTRY, consulted by find_matching_semantics) as resolving to MessageSemantics.UNKNOWN. This is distinct from vocabulary-level resolution: an activity whose type is absent from the AS2 vocabulary is rejected at parse (MV-01-001) and never reaches this stage.

Two registries look up the activity on the same value, so an "unrecognized type" message alone does not tell which registry refused it. A refusal at parse time and a route to UNKNOWN are both correct answers, to two different questions. The registry name in the message tells them apart. When the system routes an unmatched semantic pattern to UNKNOWN, it logs the activity and continues. The dispatch pipeline does not fail.
Extends: MV-01-005
See also: MV-01-001 — context for the reader
MV-01-007 MUST NOT The semantic-dispatch stage MUST NOT propagate internal dispatch errors to callers.

Propagating internal errors exposes implementation details to senders and can cause the inbox handler to return unexpected error responses.
Extends: MV-01-005

Schema Validation

ID Priority Requirement Related
MV-02-001 MUST The system MUST use Pydantic models to validate activities

A Pydantic model declares one schema for each activity type and checks it when it builds the object. Thus each activity that a handler gets already has the field types and required fields of its type. Hand-written checks can become different from the classes that they protect.
Implements: VP-15-001
MV-02-002 MUST The system MUST reject activities that fail Pydantic validation with HTTP 422

A 422 status tells the sender that the receiver could read its message but that the message is not a valid activity. The sender can then correct the content and not send the same message again. If the receiver processes an invalid activity, its handlers act on data that the schema identifies as incorrect.
MV-02-003 MUST Validation error responses MUST include detailed error information

A sender can correct a refused activity only if it knows which field failed and why. A refusal without this data leaves a peer implementer to guess.
MV-02-004 MUST The system MUST log validation failures at WARNING level

A validation failure means that a peer sent data that Vultron could not use. The receiver recovers when it refuses the data, but an operator must see the failure. The log is the only record that the receiver keeps of a message that it refused.

Object Type Validation

ID Priority Requirement Related
MV-04-003 MUST This rule covers an inline object whose type resolves to a known wire vocabulary class but fails validation against that class. A receiver MUST reject the enclosing activity as malformed, not substitute a less specific type. Inside a preview, the class is the loose form the field declares (MV-12-006).

If the parser uses a weaker type in place of the correct one, it loses data silently: an Accept(Invite(...)) with one corrupt inner field can parse as a bare as_Link, get the semantic type UNKNOWN and a 202 status.
MV-04-004 MUST When a receiver resolves the type of an inline object, it MUST consider only wire-branch classes. An unresolved type leaves the object for its parent field to validate.

A refusal under MV-04-003 is safe only when resolution looks at wire classes alone. A CORE_TYPE_MAP fallback (ARCH-12-014) resolves an inline actor's inbox to a core instance that its wire parent refuses (ARCH-22-001). The core fallback is opt-in (VM-06-013).
Extends: MV-04-003
MV-04-005 MUST A Link MUST carry a non-empty href, whether it is received or built locally.

A Link names its resource by href (AS2 Vocabulary § 3.2), so a Link without one names nothing. If a Link could lack an href, every untyped inline object that failed its object class would fall through the slot's union to an empty Link, and its content would be lost without a trace (#5715). With the href required, such an object is refused instead.
Extends: MV-04-003

Outbound Activity Object Integrity

ID Priority Requirement Related
MV-09-002 MUST The outbox handler MUST raise VultronOutboxObjectIntegrityError and abort delivery when an outbound initiating activity's sealed body carries a bare string or an as_Link as object.

The outbox sends the body that the act sealed, so the factory must put the object inline. A reference in object is a factory defect, and the refusal names it.
MV-09-004 MUST NOT The outbox handler MUST NOT expand a reference in the object of a sealed body from the DataLayer before MV-09-002 refuses it.

The outbox is a dumb relay (VM-08-003). If delivery expands a reference, the sent body is different from the body that the act recorded. This also hides the factory defect that made the reference.
Extends: MV-09-002
MV-09-003 MUST Vultron activity classes where semantic dispatch depends on the object_ type MUST require object_ at construction time — no None default is permitted. An omitted or None object_ renders the activity semantically meaningless because ActivityPattern._match_field returns False for None, causing every pattern that inspects object_.type to fail, which forces dispatch to UNKNOWN.

A pattern that examines the type of the object fails when the object is missing. Thus an activity built without an object always goes to UNKNOWN. When the field is required at construction, this silent routing error becomes an error at the point where the code builds the activity.

Stub Objects

ID Priority Requirement Related
MV-10-003 MUST NOT The DataLayer MUST NOT overwrite a full domain object with a stub object

A recipient may receive a stub for an object they already have in full; discarding preserves data completeness
MV-10-004 MUST NOT Inbound stubs MUST NOT be used to create new domain records

A stub has only an id, a type and a summary. A record built from a stub is an empty copy, and later reads use it as the real object. The full case arrives only when the participant is active (MV-10-005), and a record created from the stub goes around that gate.

Inbound Unknown-Key Disposition

ID Priority Requirement Related
MV-11-001 MUST The parse edge (parse_activity in vultron/wire/as2/parser.py) MUST decide what happens to an unrecognised key on inbound data for every object at every depth. It decides by partitioning the arriving keys against the resolved class's declared spellings before it validates the object. The objects are the activity envelope, and an inline object whose type resolves to a wire class or to a core class. They also include an inline Link, and an inline object with no type. They include each object in a fetched body (AKM-05-007), which parse_fetched_object in vultron/adapters/driven/http_object_fetch.py partitions the same way. A declared spelling is a field name, the camelCase alias the class generates for it, an explicit validation alias, or @context.

Without one rule at the parse edge, the result for an unknown key depends on the class of its object. A core class with extra="forbid" (ARCH-12-003) refuses the key with a 422 status. A wire class with the Pydantic default extra="ignore" drops the key silently. Neither result is a decision of the receiver. Under one object model (ADR-0211), the parser is the inbound point where wire data becomes core data (ADR-0032: validate at the edge; ARCH-21-002: inbound wire data stays lenient).
Part of: ARCH-25-007
Constrains: AKM-05-007
MV-11-006 MUST NOT The disposition of an unrecognised inbound key (MV-11-001) MUST NOT depend on which branch the resolved class belongs to.

A peer cannot see whether Vultron models an object as a wire class or a core class. If the branch decided the result, one unknown key would be refused on one object and dropped on another, and that split is configuration, not a decision.
Refines: MV-11-001
MV-11-002 MUST This rule covers an unrecognised inbound key that is a near miss of a declared spelling of the resolved class. A receiver MUST refuse the whole activity, with the schema-fault response that MV-02-002 requires. A key is a near miss when lowercasing it and removing every non-alphanumeric character yields a declared spelling treated the same way. Thus Actor, attributed-to and ATTRIBUTEDTO are near misses of actor and attributedTo. A spelling the resolved class accepts on input is declared, never a near miss. Both roots validate by field name as well as by alias (CS-14-001, CS-14-002), so attributed_to is a declared spelling of attributedTo. The JSON-LD keywords @id and @type are near misses of id and type by design.

A near miss is a key that the sender intended Vultron to read. If the receiver goes on without the key, it loses the sender's data and writes only a log line. A refusal tells the sender which field to correct. A name that the protocol once read and no longer reads is not a near miss: before 1.0 this codebase supports one protocol version, so it keeps no list of such names, and the key is an ordinary unknown key (MV-11-003, ADR-0175). AS2 spells id and type with no @ prefix, because the AS2 context aliases the keywords (AS2 Core section 2.1). So a document that carries @id or @type is legal JSON-LD but not conforming AS2 (MV-01-001).
Refines: MV-11-001
Uses definition from: MV-02-002
Part of: ARCH-25-007
See also: CS-14-001 — context for the reader
See also: CS-14-002 — context for the reader
MV-11-007 MUST NOT A receiver MUST NOT make @id or @type a declared spelling, as an alias or by exemption from the near-miss test (MV-11-002). The only JSON-LD keyword that is a declared spelling is @context.

The keywords stay near misses so that the peer sees the refusal as a decision. A peer that sends @id or @type did not compact its JSON-LD, or used a context without the AS2 aliases. It intended the id and type that Vultron reads. If the parser ignores the keywords, the object loses its identity and type, and more refusals follow. If Vultron declares the keywords as aliases, it becomes a partial JSON-LD processor with no clear limit.
Refines: MV-11-002
MV-11-008 MUST The refusal of MV-11-002 MUST name the arriving key and the declared spelling it resembles.

The refusal tells the peer the compact form to send. A refusal that names only the arriving key leaves the sender to guess which field Vultron meant.
Extends: MV-11-002
MV-11-009 MUST The near-miss test (MV-11-002) MUST use exactly its normalisation, and no edit distance, prefix match or other similarity measure.

The normalization is shallow on purpose. AS2 has many property names of two or three letters that are one character apart, so an edit-distance model gives many false matches. A wider definition of "near" is not worth its cost (ARCH-25-008; ADR-0211).
Refines: MV-11-002
MV-11-003 MUST A receiver MUST set aside and report, not refuse, an unrecognised inbound key that is not a near miss. The activity proceeds on its declared fields. The receiver logs one INFO record per set-aside key with activity_id, the sender's actor_id, the dotted field path of the key's object, and the key. For a fetched object (MV-11-001), the record names its object_id instead, and the actor that served it as actor_id.

AS2 is designed for extension. Some peers send properties that Vultron does not read. If the receiver refuses each such message, peers lose interoperability, and the protocol gets no benefit. But the receiver must not stay silent. An operator must see what peers send that Vultron ignores. Also, a misspelling in Vultron that the near-miss test does not find shows here first.
Refines: MV-11-001
Part of: ARCH-25-007
MV-11-010 MUST NOT A receiver MUST NOT carry a set-aside key (MV-11-003) into the parsed object or into any dump of it. The raw body remains available as received evidence (VM-08-002).

If the parser keeps the key on the object, the key goes into the stored form, and extra="forbid" refuses it when the object is validated again. Thus the report is the only record of the key, and the received evidence is its only copy.
Extends: MV-11-003
See also: VM-08-002 — context for the reader

Meta-Specification Style Guide

Normative rules for authoring specification files in this project. Covers file structure, requirement format, IDs, writing rules, cross-references, lifecycle, quality criteria, and the delineation between spec files and ADRs.

File ID: MS

ADR Status as Confidence Signal

ID Priority Requirement Related
MS-14-005 MUST ADR frontmatter MUST validate against the AdrFrontmatter Pydantic model (vultron/metadata/adr/schema.py). The loader (vultron/metadata/adr/loader.py) enforces it via pytest and pre-commit, mirroring the notes frontmatter registry (NF-03, NF-04).

ADRs are the confidence signal agents trust as ground truth. A Pydantic model makes status typechecking real validation rather than string-scraping. See ADR-0043.
MS-14-016 MUST A retired ADR MUST carry a superseded_by pointer that resolves to a real ADR file.

A retired ADR with no pointer leaves a reader with no way to find the decision that replaced it, and a pointer to a missing file is the same dead end. The loader checks both, so a dangling target cannot merge.
Extends: MS-14-005
MS-14-006 MUST docs/adr/index.md MUST be generated from ADR frontmatter (uv run adr-index --write). CI (uv run adr-index --check) fails on drift.

A hand-maintained index rots: an ADR can be filed under the wrong index section. Generating it makes that drift mechanically impossible to merge. See ADR-0043 and MS-14-003.
MS-14-017 MUST NOT An ADR, archived or not, MUST NOT be referenced in the mkdocs nav. Readers reach it through the generated index.

Decision records are project working record, which stays out of the reader-facing nav (DF-11-003), and the generated index is their routing page (DF-11-006).
MS-14-018 MUST Each ADR, archived or not, MUST be matched by the not_in_nav patterns in mkdocs.yml.

An ADR in neither the nav nor not_in_nav breaks mkdocs --strict on an omitted-file warning, so the check requires the pattern match too.
Derives from: MS-14-017
MS-14-011 MUST ADR supersession links MUST be recorded in both directions. Each superseded_by or partially_superseded_by entry on an ADR is matched by a supersedes or partially_supersedes entry on the ADR it names. Each successor-side entry is matched by the reverse pointer on the ADR it names.

When only the forward pointer is checked, the successor side becomes out of date. An agent that reads the successor must see what it replaced.
Extends: MS-14-005
MS-14-027 MUST Each of the four supersession fields MUST accept a list of ADRs as well as a single ADR.

A successor can retire several ADRs, and a single-value field cannot record that.
Extends: MS-14-011
MS-14-028 MUST The ADR loader MUST fail when a supersession pair is one-sided, comparing entries by ADR number whatever form the pointer is written in.

A loader check in CI finds a one-sided link before it merges. Comparing by number keeps two forms of the same pointer from reading as a mismatch.
Verifies: MS-14-011

Metadata Loader Failure Attribution

Rules for how the file-walking loaders under vultron/metadata/ report a file they cannot read. These loaders back the pre-commit hooks and the spec-dump / spec-lint / append-history / adr-index entry points, so their error output is the first thing an author sees after a bad edit.

ID Priority Requirement Related
MS-17-001 MUST A loader under vultron/metadata/ that walks a set of files and validates each one MUST attribute every failure to the file that caused it, naming the repository-relative path and — when the underlying parser supplies a position — the line and column, in the form path:line:col. A message that reports only a position, or only a positional index into the parsed structure, does not satisfy this requirement.

Each of these loaders reads a whole directory, so a position without a filename identifies nothing: the corpus under specs/ alone spans dozens of files in which "line 404" is ambiguous. PyYAML compounds this, because a loader that hands it text rather than a named stream gets a mark reading <unicode string> — a position attributed to a source that does not exist on disk. The file name is knowledge only the loader holds, so only the loader can supply it.
MS-17-002 MUST NOT A YAML parse error or a schema-validation error MUST NOT escape such a loader as an unhandled traceback.

A traceback replaces the tool's own error format, and no frame in it names the offending file. Which step raised also decides the output's shape: a parse fault escapes as a traceback and suppresses the loader's own reporting, while a validation fault is caught and rendered as the tool's error line.
MS-17-005 MUST Such a loader MUST report both the parse fault and the model-validation fault of each file as a ValueError. That is the type these loaders already document raising.

A YAML scanner error is not a ValueError, so a caller guarding except (ValidationError, ValueError) never sees it and the tool exits through a traceback instead of its own error format.
Implements: MS-17-002
MS-17-003 MUST The attribution required by MS-17-001, MS-17-002 and MS-17-005 MUST come from one shared helper in vultron/metadata/file_loading.py, not a copy per loader. Each loader that walks files routes both its parse step and its validation step through that helper.

The same wrapper was written independently in the ADR loader and in the history entry loaders, in as many message shapes as there were copies, while the notes and spec loaders were left without one — so what an author sees depends on which directory they edited rather than on what they got wrong. A shared helper is also the only way an improvement reaches all of them: no hand-written copy read the parser's position mark, and the history CLI's copy reported no path at all.
Implements: MS-17-001
Implements: MS-17-002
Implements: MS-17-005
MS-17-004 MUST An exception class raised by the shared helper to report loader failures MUST be a ValueError subclass defined within the tooling layer.

VultronError derives from Exception, not ValueError, so a caller guarding except (ValidationError, ValueError) would miss an error of that hierarchy as it misses a scanner error. A ValueError subclass keeps the documented guard working.
Refines: MS-17-005 — fixes the concrete exception type that satisfies the ValueError requirement
MS-17-006 MUST NOT Code under vultron/metadata/ MUST NOT extend the VultronError hierarchy that EH-01-002 requires of protocol code.

SR-03-009 makes the shared helper's exception the tooling layer's first custom exception class, which is what brings EH-01-002 into contact with it. Obeying EH-01-002 here would invert the loader contract of MS-17-004. vultron/errors.py is the protocol domain's; this is tooling.
Extends: MS-17-004
See also: EH-01-002 — scope boundary: EH-01-002 excludes vultron/metadata/

Multi-Actor Demo

Requirements for multi-actor demo scenarios, Docker Compose orchestration, actor isolation, acceptance testing, and reproducibility. Includes per-scenario required semantic-type lists for the case-ledger invariant harness.

File ID: DEMOMA

Cross-Actor Communication

ID Priority Requirement Related
DEMOMA-00-001 MUST Cross-actor communication MUST occur exclusively via HTTP using the ActivityStreams inbox endpoint

A demo exists to show that the protocol works between separate actors. If actors exchange data by any path other than the HTTP inbox, the demo can pass while the delivery path that real deployments use is broken. HTTP delivery to the ActivityStreams inbox is the only path that a real peer has.
DEMOMA-00-002 MUST NOT A scenario under vultron/demo/scenario/, and the helper code it calls, MUST NOT post an activity to the inbox of any actor.

Delivery is the job of the transport. When a scenario delivers an activity itself, the outbox, delivery and inbox path never runs, and demo CI proves nothing end to end. The rule has no self-delivery exception: an actor's replica updates from the CaseActor's Announce, so a replica that does not update means that the routing is wrong. The exchange demos under vultron/demo/exchange/ drive one backend directly and are outside this rule.

Actor Isolation

ID Priority Requirement Related
DEMOMA-01-001 MUST Each actor in a multi-actor demo MUST run in a separate container with its own DataLayer instance

Separate containers with separate DataLayers give each actor only the state that the protocol delivers to it. If two actors share a store, one actor can read the state of another actor directly. Then the demo can pass although the messages between them are missing or wrong.
DEMOMA-01-002 MUST Each actor container MUST expose the actor's identity via its /actors/{actor_id} profile endpoint so that other containers can discover it at startup

Other containers must find an actor before they can send to it. The profile endpoint is the standard way that an ActivityStreams peer learns the inbox and identity of an actor. Without it, each container must hard-code its peers, and a wrong address shows only as a failed delivery later in the run.
DEMOMA-01-003 MUST Demo startup MUST automatically reset all actor state to a known clean baseline before the scenario executes, without requiring manual user intervention

State left from an earlier run can satisfy a check that the current run did not earn, or it can cause a failure that the current code did not cause. An automatic reset to a known baseline makes each run start from the same state, so that a result tells you about the current code. A manual step is easy to forget, and CI cannot do it.
DEMOMA-01-004 MUST Each call to create_app() MUST create fresh per-app instances of the dispatcher, the emitter and the DataLayer, stored on app.state.

When multiple Vultron actors are co-located in the same Python process (e.g., a report-receiver actor and its spawned Case Actor), each call to create_app() must produce a fully isolated application.
DEMOMA-01-006 MUST NOT create_app() MUST NOT mutate module-level singleton state, such as _DEFAULT_EMITTER_SLOT, _DISPATCHER_SLOT or _shared_instance.

If create_app() mutates module-level globals, the last lifespan to call configure_default_emitter() or init_dispatcher() silently overwrites the state of all prior co-located actors, and data leaks between actors.
Extends: DEMOMA-01-004
DEMOMA-01-005 MUST Each co-located actor MUST have its own DataLayer instance in its app.dependency_overrides, shared with no other app in its process. A co-located actor is one of several FastAPI app instances in one process.

Sharing a DataLayer instance across co-located actors bypasses the outbox → inbox delivery path: objects created by Actor A become immediately visible to Actor B without any delivery occurring. This makes integration tests unreliable and hides real cross-actor delivery bugs.
DEMOMA-01-007 MUST Each co-located app MUST resolve its own AppConfig, shared with no other app in its process. The app's requests read that config, and so does the work it runs outside a request. That work is BackgroundTasks, outbox delivery, the sender-sequence hold timer, the ledger position statements and the startup inbox replay.

In Docker each container is one node with its own config. When every app in one process read one config, a node that read its own config for another actor's fact passed in process and failed only in Docker (#1876). A config per app makes the in-process suite fail where Docker fails. A read that lost its app's scope raises VultronWiringError, so a dropped scope fails loudly instead of reading the wrong node's settings.
Extends: DEMOMA-01-004

Container Orchestration

ID Priority Requirement Related
DEMOMA-02-001 MUST Docker Compose configurations for multi-actor demos MUST include a healthcheck for each actor service that probes the /health/ready endpoint

A container can be running before its API can accept requests. A healthcheck on /health/ready lets Docker Compose know when each actor can receive messages. Without it, the first triggers of a scenario can fail for reasons that have nothing to do with the protocol.
Extends: IMPLTS-05-002 — tech-stack.md
Depends on: OB-05-002 — observability.md
DEMOMA-02-002 MUST Dependent services (e.g., a demo orchestration container) MUST use condition: service_healthy for all actor service dependencies

A depends_on entry without condition: service_healthy waits only for the container to start, not for the actor to be ready. The demo runner can then send its first request to an actor that cannot answer it. The condition uses the healthcheck (DEMOMA-02-001) to hold the runner until every actor is ready.
DEMOMA-02-003 MUST Port mappings, network names, and required environment variables MUST be documented in the docker-compose.yml file or an accompanying README.md

A developer who runs or debugs a demo must know which port reaches which actor and which variables configure it. If this information is only in the code, each person must find it again, and a wrong value gives a failure that is hard to diagnose. A record next to the Compose configuration keeps it in one known place.

Acceptance Tests

ID Priority Requirement Related
DEMOMA-03-001 MUST Each multi-actor demo scenario MUST include an acceptance test that validates the end-to-end workflow deterministically

A scenario script can run to the end without proof that the protocol did what the scenario claims. An acceptance test checks the result of the complete workflow. A deterministic test gives the same verdict for the same code, so a failure points to a defect and not to chance.
DEMOMA-03-002 MUST Acceptance tests MUST assert final state for each actor (e.g., correct RM/EM/CS state, expected case ledger entries)

A run that ends without an error can still leave an actor in the wrong RM, EM or CS state, or with a ledger that is missing an entry. Checks on the final state of each actor find these defects. Checks on one actor only cannot find a replica that did not receive an update.
DEMOMA-03-003 MUST An acceptance test MUST produce the same result on successive runs of the same codebase.

A test that passes on one run and fails on the next gives no information about the code. Developers then learn to ignore its failures, and a real defect can hide among them. A reproducible test lets a failure count as evidence.

Scenario Coverage

ID Priority Requirement Related
DEMOMA-04-002 SHOULD Each scenario SHOULD include a summary of the expected CVD workflow steps and the expected final RM/EM/CS state for each actor

A reader must know what the scenario is expected to do before the reader can judge whether a run is correct. A summary of the expected workflow steps and final states gives that reference. Without it, the script itself becomes the only description of the expected result, and a wrong script then looks correct.

Demo Trigger Protocol

ID Priority Requirement Related
DEMOMA-05-001 MUST All actor-initiated actions in scenario demos MUST be driven through the trigger API (POST /actors/{actor_id}/trigger/{behavior-name}), not by direct inbox injection or other mechanisms that bypass the actor's own protocol logic

Using trigger endpoints ensures that the demo exercises the same code paths that a real actor would use, including BT execution, outbox queuing, and downstream cascading behaviors. Direct inbox injection spoofs protocol messages and does not validate that the initiating actor's behavior is correctly implemented.
Depends on: TRIG-01-001 — trigger endpoint format
DEMOMA-05-002 MUST NOT Scenario demo scripts MUST NOT construct and POST raw ActivityStreams JSON directly to an actor's inbox as a substitute for calling that actor's trigger endpoint

A demo script that posts raw ActivityStreams JSON to an inbox creates a message that the sending actor did not decide to send. Its behavior tree does not run, so the demo cannot find a defect in that logic. The trigger endpoint is the path on which the sending actor makes the decision itself (DEMOMA-05-001).
Derives from: DEMOMA-05-001
DEMOMA-05-003 MAY An exchange demo under vultron/demo/exchange/ MAY use direct inbox injection to simulate the receipt of a specific wire message. Direct inbox injection builds and posts raw ActivityStreams JSON.

Exchange demos are low-level wire-format verification scripts that intentionally exercise the inbox parsing path directly. This carve-out resolves the apparent contradiction between DEMOMA-05-001 (which would prohibit exchange demos) and the existing vultron/demo/exchange/ code.
DEMOMA-05-005 MUST NOT A scenario demo under vultron/demo/scenario/ MUST NOT use direct inbox injection.

DEMOMA-05-001 and DEMOMA-05-002 apply to scenario demos without exception. A scenario demo must exercise the full actor behavior, trigger dispatch included. Direct inbox injection bypasses the BT of the triggering actor, so the scenario does not test the protocol from end to end.
Derives from: DEMOMA-05-001
DEMOMA-05-004 MUST NOT Demo trigger endpoints and demo helper functions MUST NOT manipulate an actor's DataLayer directly (e.g., calling add_participant_status or equivalent) or write directly to an actor's outbox as a substitute for invoking a triggerable use case. Puppeteering an actor means calling a trigger endpoint that invokes the actor's own use case, which in turn emits the correct protocol message and awaits any required round-trip confirmation (e.g., a CaseActor ledger entry).

Direct DataLayer writes bypass the protocol entirely: no ActivityStreams message is emitted, no CaseActor ledger round-trip occurs, and the actor's local state is never established through the protocol. This produces demos that appear to work but do not exercise the real protocol path. For example, a demo that stamps RM.CLOSED directly via add_participant_status gives the appearance that the participant left the case, but no Leave(VulnerabilityCase) message was ever sent or confirmed by the CaseActor.
Derives from: DEMOMA-05-001

rv Scenario Workflow

Trigger: Scenario Start — rv

ID Priority Requirement Related
DEMOMA-06-001 MUST The rv (Reporter + Vendor) demo scenario MUST execute a complete CVD lifecycle ending in final case state VFDPxa (Vendor aware, Fix ready, Fix Deployed, Public aware, no exploit public, no active attacks)

The rv scenario is the smallest scenario that runs the complete CVD lifecycle between two parties. VFDPxa is the state in which the fix is ready and deployed and the public is aware. A run that ends in any other state has not completed the lifecycle that this scenario exists to show.
DEMOMA-06-002 MUST The rv scenario script MUST verify the following protocol checkpoints in order, checking both the Vendor and Reporter DataLayers at each checkpoint: (1) report received (RM.RECEIVED), (2) report validated (RM.VALID), (3) case engaged (RM.ACCEPTED), (4) embargo active (EM.ACTIVE), (5) fix ready (CS.VFd), (6) fix deployed (CS.VFD), (7) publicly disclosed (CS.VFDPxa).

Each checkpoint is a protocol event on which the next events depend. A check on the final state alone cannot show which step failed. A check on one DataLayer alone cannot show whether the update reached the other actor. Ordered checks on both DataLayers find the first step that went wrong and the actor that did not get the update.

ECA Details

Preconditions

- Two-actor scenario executing; Vendor, Reporter, and CaseActor containers running and reachable; report submitted by Reporter to Vendor

Steps

1. [demo-script] Verify case creation: 3 participants (Vendor, Reporter, CaseActor) and EM.ACTIVE; check Vendor DataLayer → Vendor DataLayer holds VulnerabilityCase with 3 participants and EM state = ACTIVE
2. [demo-script] Verify case replica sync: Reporter has case replica with matching participant index and active embargo; check Reporter DataLayer → Reporter DataLayer holds case replica; participant index matches Vendor's; embargo state = ACTIVE
3. [demo-script] Verify notes exchange: check both DataLayers for question note and reply note → Question note and reply note both present in canonical case state on Vendor and Reporter replicas
4. [demo-script] Verify fix-ready state: CS.VF on all replicas → Vendor and Reporter replicas both show CS = VF (vendor aware, fix ready)
5. [demo-script] Verify fix-deployed state: CS.VFD on all replicas → Vendor and Reporter replicas both show CS = VFD (fix deployed)
6. [demo-script] Verify public-disclosure state: CS.VFDPxa and EM terminated on all replicas → All replicas show CS = VFDPxa; EM state = EXITED
7. [demo-script] Verify case close: all participants RM.CLOSED and case closed → All participants RM state = CLOSED in the CASE_MANAGER's store; case record marked closed; each participant's replica ends at the entries recording its own closure (CM-23-004)

Postconditions

- All checkpoints verified; rv scenario complete in final state VFDPxa with EM.EXITED and all participants RM.CLOSED

DEMOMA-06-003 MUST Milestone verification MUST read both the Vendor DataLayer and the Reporter DataLayer directly.

A demo must observe the state of an actor to verify it, and a direct read does not change what the protocol did. Direct reads are thus acceptable in demo scripts as read-only assertions.
DEMOMA-06-010 MUST NOT A demo script MUST NOT use direct DataLayer access to write or manipulate actor state.

A write puts state into an actor that the protocol did not put there, and the demo can then pass although the protocol failed (DEMOMA-05-004).
Derives from: DEMOMA-05-001
DEMOMA-06-004 MUST The rv demo Docker topology MUST use a dedicated case-actor container with its own isolated DataLayer.

A case-actor container of its own satisfies DEMOMA-01-001 (each actor in its own container) and exercises the CaseProposal protocol (ADR-0023) in the rv scenario.
Refines: DEMOMA-01-001
DEMOMA-06-008 MUST The Vendor MUST route case-actor creation to the dedicated container through ActorConfig's pre-configured case_actor_service_url, not a URL derived from server_base_url (CP-08-001 to CP-08-003).

The case setup nodes read case_actor_service_url from ActorConfig through case_actor_identity(), so the Vendor container must supply VULTRON_ACTOR__CASE_ACTOR_SERVICE_URL pointing to the dedicated CaseActor container (CP-08-003). A URL derived from server_base_url names the Vendor's own container instead.
Extends: DEMOMA-06-004
Depends on: CP-08-001
Depends on: CP-08-003
DEMOMA-06-005 MUST After the demo completes, the rv demo MUST verify that the DataLayer of the case-actor container holds the canonical case ledger.

The dedicated case-actor container holds the canonical case and ledger (DEMOMA-06-004). A check of that ledger shows that the canonical case history is complete, not only the replicas.
Verifies: DEMOMA-06-004
DEMOMA-06-009 MUST The rv demo script MUST dump the ledger of the case-actor from the dedicated case-actor container, not from the co-located sub-actor of the vendor container.

A ledger read from another container can be a replica or an old local copy. A check on that ledger can pass although the canonical ledger is wrong or empty.
Extends: DEMOMA-06-005
DEMOMA-06-006 MUST Before a demo script calls verify_fix_ready, verify_fix_deployed or verify_publicly_disclosed, it MUST poll for the checked state on every container that the helper asserts against. This includes the receiver container. The polling waits are wait_for_participant_vf_state and wait_for_participant_d_state. Using a polling wait only on the reporter container and then immediately asserting on the receiver container with a single-shot check is not permitted.

A demo step must wait for its cause, not for a fixed time or a fixed order (ADR-0058). A VFD change reaches each container through Add(CaseLedgerEntry), at a time that nobody can predict. verify_fix_ready and verify_fix_deployed check each container once and do not retry. Thus a check on a container that has not yet received the change fails, although the protocol is correct. A wait on every container that the helper checks makes the check depend on the change, not on timing.
Extends: DEMOMA-06-002
DEMOMA-06-007 MUST The rv story MUST start with the shared "the Reporter tells the Vendor" opening and continue from the replica synchronization it checks next.

The opening is the Reporter submitting its report to the Vendor and the Vendor validating it and engaging the case. rv tells it identically to RVV, RVCV-extension and RVCV-handoff, so it is one copy of the code and the four recordings are byte-identical up to the Vendor's decision (DEMOCI-11-018). rv then reads two replica checks of its own before the note thread its siblings post next; both write nothing, so they move no byte of the shared opening. Naming the opening here keeps this group a whole story: a reader sees where rv's own telling begins without reading a sibling's group.
Refines: DEMOMA-17-001

ParticipantStatus Trigger Pattern

ID Priority Requirement Related
DEMOMA-07-001 MUST CS state transitions (fix-ready, fix-deployed, published) MUST be driven through participant status updates via Add(ParticipantStatus, target=/statuses) sent to the Case Actor inbox, not through dedicated low-level state-machine endpoints. RM case closure is explicitly excluded from this requirement: RM.CLOSED MUST be reached via the Leave(VulnerabilityCase) round-trip (CM-23-001), not via an Add(ParticipantStatus) whose status carries rmState=CLOSED.

CS transitions are participant facts, so they travel as Add(ParticipantStatus) to the CASE_MANAGER, which commits them to the case ledger. A dedicated state-machine endpoint would change state with no message and no ledger entry. RM closure is different: the participant leaves the case. The Leave(VulnerabilityCase) round-trip makes the CASE_MANAGER the authority for that departure, so a participant cannot be closed on its own replica while its peers never learn of it (ADR-0050).
Implements: CM-23-001
DEMOMA-07-002 MUST Demo trigger endpoints for participant status transitions MUST use the "notify" naming convention (e.g., notify-fix-ready, notify-fix-deployed, notify-published) to avoid semantic collision with the ActivityStreams Announce verb

Announce is an ActivityStreams verb that the protocol uses for case replication. A trigger named announce-fix-ready would suggest that the trigger sends an Announce activity, but it sends Add(ParticipantStatus). The notify names describe what the actor does without that confusion.
DEMOMA-07-003 MUST The Case Actor received handler for ADD_PARTICIPANT_STATUS_TO_PARTICIPANT MUST implement these ordered steps as a BT Sequence. (1) It verifies that the activity actor is a known case participant (precondition guard). (2) It updates the participant status record. (3) It propagates the update with Add(CaseLedgerEntry) fan-out (ADR-0019, SYNC-02-001, SYNC-02-003), never a re-broadcast of a direct raw Add(ParticipantStatus). It sends it to the other participants that receive case content (CM-10-004, CM-23-004). (4) If the Case Owner newly sets CS.P, it triggers embargo teardown automatically. (5) If all participants are RM.CLOSED, it closes the case automatically.

The CASE_MANAGER must check the sender before it changes a record, and it must commit the change before it tells other participants about it. A BT Sequence makes this order part of the tree structure. A step hidden inside one node's update() method cannot be seen or tested on its own, and it can be skipped or reordered without notice.

ECA Details

Preconditions

- Receiving actor is CASE_MANAGER (Case Actor)
- Inbound activity actor is a known case participant

Steps

1. [case_actor] Verify inbound activity actor is a known case participant → Actor found in case.actor_participant_index; FAILURE if unknown sender
2. [case_actor] Append ParticipantStatus to the participant record → Participant's latest status reflects the newly received state
3. [case_actor] Commit a canonical CaseLedgerEntry and fan-out Add(CaseLedgerEntry) to the case's content recipients (CM-10-004, CM-23-004) → Every active peer not at RM.CLOSED receives the status update via the canonical log path (ADR-0019, SYNC-02-003), and so does a closed participant the entry records the closure of; no other closed participant receives it, and no raw Add(ParticipantStatus) re-broadcast is emitted
4. [case_actor] If the new CaseStatus (derived from the participant status update) indicates at least one of CS.P, CS.X, or CS.A and an active embargo exists, trigger embargo teardown automatically via ThreatTerminationBranchNode (RSH-03-001). The teardown runs in the act that adopts the value, with no separate teardown gate: the adoption also authorizes it (RSH-07-001, ADR-0210). The teardown fires for any adopted participant's CS.P/X/A, not only the Case Owner's. See ThreatTerminationBranchNode (RSH-03-002: no sender-role gate) and ADR-0046. → Embargo teardown triggered (EM.EXITED) when any participant's CaseStatus carries CS.P, CS.X, or CS.A and an active embargo is present
5. [case_actor] SUPERSEDED This step previously described an all-participants-RM.CLOSED check that emitted Leave(VulnerabilityCase) from the Case Actor to trigger case closure. This step is retired: RM case closure now flows through each participant's own Leave(VulnerabilityCase) round-trip (CM-23-001). The owner-Leave path (CM-23-002) replaces this step; when the Case Owner sends Leave(VulnerabilityCase), the Case Actor closes the case and advances the CaseActor participant to RM.CLOSED (CM-23-004, ADR-0051). Implementation: see #1901. → SUPERSEDED No AutoCloseSequence fires in add_participant_status_tree. Case closure is triggered by Leave(VulnerabilityCase) from the Case Owner.

Postconditions

- Participant record updated; CaseLedgerEntry committed and broadcast; embargo teardown triggered when any participant's CaseStatus carries CS.P, CS.X, or CS.A and an active embargo exists.

Uses definition from: CM-10-004
Uses definition from: CM-23-004
See also: SYNC-02-001 — provenance for the fan-out's envelope; the step names the Add it sends and neither narrows nor needs SYNC-02-001's rule
See also: SYNC-02-003 — provenance for the fan-out; its recipients come from CM-10-004 and CM-23-004, which are linked
DEMOMA-07-007 MUST The Case Actor MUST implement each step of the DEMOMA-07-003 sequence as a distinct BT node or subtree.

A distinct node for each step keeps the protocol logic visible in the tree structure. A step hidden inside the update() method of one node cannot be seen or tested on its own, and it can be skipped or reordered without notice.
Extends: DEMOMA-07-003
DEMOMA-07-006 MUST SUPERSEDED by CM-23-001 and ADR-0050 The BT node decomposition requirements for DEMOMA-07-003 step 5 (AllParticipantsRMClosedConditionNode, CloseNotYetEmittedConditionNode, EmitCloseCaseNode) are retired from the add_participant_status_tree path. Those nodes MUST NOT be wired into add_participant_status_tree; they were live dead code after PR #1909 because the AutoCloseSequence evaluated AllParticipantsRMClosedConditionNode only when Add(ParticipantStatus) arrived, which always precedes any Leave and therefore could never observe all participants at RM.CLOSED. The equivalent closure logic belongs in the Leave(VulnerabilityCase) receive path, implemented by #1901 (CM-23-002, CM-23-003, ADR-0051).

These nodes check whether all participants are at RM.CLOSED when an Add(ParticipantStatus) arrives. On that path the check cannot be true, because the status update always arrives before any Leave. Nodes that can never fire make the tree look as if it closes cases when it does not. Case closure belongs to the Leave(VulnerabilityCase) receive path (CM-23-002).
Supersedes: DEMOMA-07-003 — Step 5 is superseded; AutoCloseSequence removed from add_participant_status_tree
See also: CM-23-001 — provenance of the retired step 5
See also: CM-23-002 — provenance of the retired step 5
See also: CM-23-003 — provenance of the retired step 5
DEMOMA-07-004 SHOULD The participant status trigger implementation SHOULD be layered: SvcAddObjectToCaseUseCase (generic Add(object)[target=VulnerabilityCase]) as the base, SvcAddParticipantStatusUseCase (new core use case) above it, and demo-specific endpoints in demo_triggers.py at the top

Each layer adds one thing: the generic case use case adds an object to a case, the status use case adds the participant status rules, and the demo endpoint adds only the HTTP route for the demo. Code in one layer can then be reused by the layer above it, and the demo endpoints do not repeat the protocol logic.
DEMOMA-07-005 MUST NOT The Case Actor received handler for ADD_PARTICIPANT_STATUS_TO_PARTICIPANT MUST NOT send a raw Add(ParticipantStatus) re-broadcast directly to peer participants after updating the local participant record. Add(CaseLedgerEntry) fan-out is the sole canonical propagation path for status updates to peers (DEMOMA-07-003 step 3); a parallel raw re-broadcast causes every peer to receive and process the same status update twice — once as a raw Add(ParticipantStatus) and once wrapped in Add(CaseLedgerEntry) — producing duplicate state transitions and non-canonical messages in peer inboxes. This artefact is superseded by ADR-0019.

Each status update must reach a peer once, through the case ledger. A second raw Add(ParticipantStatus) gives the peer the same update twice, by two paths, and only one of them is a canonical ledger entry. The peer can then apply the change twice or hold a message that does not match its ledger.
Refines: DEMOMA-07-003 — prohibits the pre-SYNC raw re-broadcast artefact superseded by ADR-0019

Case Actor Bootstrap and CASE_MANAGER Role

ID Priority Requirement Related
DEMOMA-08-001 MUST The vendor MUST send Create(VulnerabilityCase) (not Announce) to the Reporter as the trust bootstrap after case initialization; only the Case Actor uses Announce for subsequent case updates.

The Reporter does not yet know the Case Actor, but it trusts the vendor to which it sent the report. A Create(VulnerabilityCase) from the vendor carries that trust to the case and to its CASE_MANAGER (CBT-01-001). After that, the Reporter can accept Announce messages from the Case Actor, which it would otherwise reject as messages from an unknown sender.
Refines: CBT-01-001 — original report submission path bootstrap
DEMOMA-08-003 MUST NOT CASE_MANAGER role delegation MUST NOT reuse or adapt the existing OFFER_CASE_OWNERSHIP_TRANSFER, ACCEPT_CASE_OWNERSHIP_TRANSFER, or REJECT_CASE_OWNERSHIP_TRANSFER message semantics; these are distinct protocol operations with different semantics and different effects on case ownership

An ownership transfer changes who is the Case Owner. A CASE_MANAGER delegation does not change the Case Owner. If delegation used the ownership-transfer messages, a receiver could not tell which change was meant, and it could apply an ownership change that nobody asked for.
DEMOMA-08-004 MUST When the Case Actor accepts the CASE_MANAGER delegation, it MUST run the case initialization BT: establish the default embargo with both Vendor and Reporter immediately as signatories (no invite/accept round-trip), and set EM state to ACTIVE before the trust bootstrap is sent to the Reporter

The Reporter consented to the default embargo of the Case Owner when it submitted the report (CM-14-005, EP-04-001), and the Vendor is that Case Owner. An invite and accept exchange for these two parties would record an invitation that did not occur. EM must be ACTIVE before the trust bootstrap, so that the Reporter receives a case that already has its embargo.
DEMOMA-08-005 MUST All nested domain objects in the bootstrap Create(VulnerabilityCase) activity (e.g., CaseParticipant objects in case_participants) MUST be embedded as full inline objects, not as bare URI string references

Receiving handlers store nested objects by iterating the embedded collection and persisting each object individually. Bare URI string references cannot be deserialized to typed domain objects; the referenced objects are never written to the receiver's DataLayer. Downstream BT nodes (e.g., SenderIsParticipantNode) then fail because participant records are absent.
Extends: CBT-01-007
DEMOMA-08-010 MUST The trust bootstrap payload MUST include all three participants (Vendor, Reporter, Case Actor) so the Reporter can bind the Case Actor identity to this case.

Without all three participants embedded in the bootstrap payload, the Reporter cannot establish trust for the Case Actor and cannot route subsequent protocol messages correctly.

RVV Scenario (Reporter → Vendor1 → Vendor2, no Coordinator)

Trigger: Scenario Start — rvv

ID Priority Requirement Related
DEMOMA-09-001 MUST The RVV scenario MUST seed three independent actor containers, Reporter, Vendor1 and Vendor2, with no Coordinator.

RVV is the scenario in which two vendors work on one case without a Coordinator. Each actor in its own container keeps the actors apart (DEMOMA-01-001).
DEMOMA-09-012 MUST Each RVV actor container MUST have its own isolated DataLayer.

A DataLayer for each actor makes sure that the vendors exchange data only through the protocol (DEMOMA-01-001).
Extends: DEMOMA-09-001
DEMOMA-09-002 MUST In the RVV scenario, after it accepts the report (RM→ACCEPTED), Vendor1 MUST invite Vendor2 to the case.

RVV has no Coordinator, so the vendor that holds the case brings in the second vendor. The invite comes after RM→ACCEPTED, because only a vendor that took the report on can invite others to work on it.

ECA Details

Preconditions

- Vendor1 RM state = ACCEPTED; VulnerabilityCase created by the CaseActor on the dedicated case-actor container; Vendor2 container running

Steps

1. [vendor1] POST invite-actor-to-case trigger for Vendor2 → CaseActor receives and queues Invite(VulnerabilityCase preview)[target=Actor] for Vendor2
2. [demo-script] Poll Vendor2 DataLayer until Invite(VulnerabilityCase preview)[target=Actor] is visible → Invite activity present in Vendor2 DataLayer
3. [vendor2] POST accept-case-invite trigger → Vendor2 joins the case and becomes a signatory (active); CaseActor seeds Vendor2 case replica

Postconditions

- Vendor2 is a signatory participant with EM consent; Vendor2 holds a seeded case replica; scenario may advance to fix tracking

DEMOMA-09-008 MUST In the RVV scenario, Vendor2 MUST accept the invite and become a full signatory participant before the scenario advances to fix tracking.

Fix tracking for Vendor2 needs Vendor2 to be a participant that is bound by the embargo. If the scenario advances before Vendor2 accepts, the later status updates from Vendor2 are refused, or they come from a party that never agreed to the embargo.
Extends: DEMOMA-09-002
DEMOMA-09-003 MUST On the replicas of the Reporter, Vendor1 and Vendor2, the RVV scenario MUST end with VFDPxa CS, and with EM.EXITED and RM.CLOSED for all participants.

The final state on all three replicas shows that each update reached every party.
DEMOMA-09-009 MUST The RVV scenario MUST track the Vendor Fix Path of Vendor1 and that of Vendor2 independently.

Each vendor has its own fix path, so the case is complete only when each vendor has reached it on its own. If the scenario tracked one fix path for both vendors, a defect in the path of one vendor would be hidden by the progress of the other.
Extends: DEMOMA-09-003
DEMOMA-09-004 MUST The RVV scenario MUST run deterministically end to end with a single docker compose command on the existing multi-actor Compose stack.

A single command makes the scenario easy to run in CI and on a developer machine.
DEMOMA-09-010 MUST After each major protocol event, the RVV scenario script MUST verify LedgerFanout replica convergence. The Reporter and Vendor2 replicas then match the authoritative Vendor1 state.

A convergence check after each major event finds the first event that did not reach a replica. A check only at the end can show that the replicas differ, but not when they became different.
DEMOMA-09-005 MUST The PR that introduces the RVV scenario script MUST also register it with the scenario registry (DEMOCI-11-001). Its generated .github/demo-scenarios.json entry (DEMOCI-11-004) then runs it as its own CI matrix job.

A scenario that is not registered does not run in CI, so it can break without notice. A separate CI job keeps each scenario failure visible on its own.
Refines: DEMOCI-03-002
Refines: DEMOCI-11-001
See also: DEMOCI-11-004 — descriptive: names the registration the scenario then has
DEMOMA-09-011 MUST The RVV CI matrix job MUST run concurrently with the rv job, not after it.

Concurrent jobs keep the elapsed time of a CI run close to the time of the slowest scenario, so total CI wall-clock time does not grow linearly with the number of scenarios.
DEMOMA-09-006 MUST The Case Actor MUST run on the dedicated case-actor container in the RVV scenario, as in every multi-container scenario; Vendor1 proposes the case to it.

RVV has no Coordinator, but the Case Actor is not a Coordinator. It is the CASE_MANAGER participant, and every actor container names the dedicated case-actor container as its case_actor_service_url (CP-08-003, CP-08-008, DEMOMA-06-008). The scenarios share one Compose stack, so RVV cannot keep the Case Actor in the Vendor1 container unless every other scenario does the same.
DEMOMA-09-007 MUST The RVV story MUST start with the shared "the Vendor answers the Reporter" opening and continue from Vendor1's decision to invite a second Vendor.

That opening is the shared "the Reporter tells the Vendor" one (DEMOMA-06-007) continued through the note thread the Reporter opens and Vendor1 answers, which is where Vendor1's decision falls. RVV tells the whole of it identically to RVCV-extension and RVCV-handoff, so it is one copy of the code and their recordings are byte-identical to the vendor-after-answer branch point (DEMOCI-11-018). Naming it here keeps this group a whole story.
Refines: DEMOMA-17-001

RVCV-Extension Scenario (Vendor1 keeps ownership; Coordinator suggests Vendor2)

Trigger: Scenario Start — rvcv-extension

ID Priority Requirement Related
DEMOMA-10-001 MUST The RVCV-extension scenario MUST involve four actor identities, Reporter, Vendor1, Coordinator and Vendor2, each with its own isolated DataLayer.

The RVCV-extension scenario needs four separate parties, and each must see only what the protocol delivers to it. Then the demo cannot pass while the messages between them are missing.
Refines: DEMOMA-01-001
DEMOMA-10-019 MUST In the RVCV-extension scenario, the CaseActor MUST run as a separate actor identity with its own container and DataLayer, not in the Vendor1 container.

A CaseActor in the Vendor1 container could share state with Vendor1 by a path that the protocol does not have. Then the demo could pass although the messages between them are missing.
Extends: DEMOMA-10-001
DEMOMA-10-002 MUST Vendor1 MUST keep CVDRole.CASE_OWNER for the whole RVCV-extension scenario, with no transfer of ownership to the Coordinator.

This scenario demonstrates the "extension" variant: a vendor seeks facilitation help without surrendering case control, in contrast to the RVCV-handoff variant where ownership transfers.
DEMOMA-10-011 MUST In the RVCV-extension scenario, Vendor1 MUST create the case (RM→ACCEPTED).

Vendor1 becomes the Case Owner when it engages the report and creates the case. The scenario needs that owner before the Coordinator can be invited to help.
Extends: DEMOMA-10-002
DEMOMA-10-003 MUST In the RVCV-extension scenario, the Coordinator MUST accept Vendor1's invitation and join the case as a participant that holds CVDRole.COORDINATOR, not CVDRole.CASE_MANAGER.

The Coordinator helps with the case but does not run it. CASE_MANAGER is the role that commits canonical case state, and in this scenario the CaseActor holds it. If the Coordinator also held CASE_MANAGER, two actors could commit case changes, and the scenario would then not show a Coordinator that helps without control.

ECA Details

Preconditions

- Vendor1 RM state = ACCEPTED; VulnerabilityCase created with CaseActor; Coordinator container running

Steps

1. [vendor1] POST invite-actor-to-case trigger targeting Coordinator → CaseActor queues Invite(VulnerabilityCase preview)[target=Actor] for Coordinator inbox
2. [demo-script] Poll Coordinator DataLayer until Invite(VulnerabilityCase preview)[target=Actor] is visible → Invite activity present in Coordinator DataLayer
3. [coordinator] POST accept-case-invite trigger → Coordinator joins the case (active) with CVDRole.COORDINATOR (not CASE_MANAGER); CaseActor seeds Coordinator case replica

Postconditions

- Coordinator is a participant with CVDRole.COORDINATOR and NOT CVDRole.CASE_MANAGER; Coordinator holds a seeded case replica

Refines: CM-20-001
DEMOMA-10-012 MUST In the RVCV-extension scenario, Vendor1 MUST invite the Coordinator to the case.

Vendor1 is the Case Owner, so it decides who joins the case. The Coordinator joins only through an invitation from Vendor1.
Extends: DEMOMA-10-003
DEMOMA-10-004 MUST In the RVCV-extension scenario, the Coordinator MUST suggest Vendor2 to the case.

A participant that is not the Case Owner cannot add a party to the case. It can only suggest one. This step drives that suggestion through the Coordinator's own trigger.

ECA Details

Preconditions

- Coordinator is an accepted participant (DEMOMA-10-003 complete); Vendor2 container running; no existing suggestion for Vendor2 in the case

Steps

1. [coordinator] POST suggest-actor-to-case trigger for Vendor2 → Coordinator sends Offer(Actor)[target=VulnerabilityCase] to CaseActor inbox
2. [case-actor] Transform Offer(Actor)[target=VulnerabilityCase] to Offer(CaseParticipant)[target=VulnerabilityCase] naming Vendor2 with roles [vendor] → Transformed offer forwarded to Vendor1 (Case Owner) inbox
3. [demo-script] Poll Vendor1 DataLayer until transformed Offer(CaseParticipant) is visible → Transformed offer present in Vendor1 DataLayer

Postconditions

- Vendor1 holds a pending Offer(CaseParticipant) for Vendor2 awaiting approval; no invitation has been sent to Vendor2 yet

Uses definition from: CM-16-001
DEMOMA-10-013 MUST The CaseActor MUST transform the Coordinator's suggestion of Vendor2 and forward it to Vendor1 for approval.

The CASE_MANAGER changes the suggestion into an Offer(CaseParticipant) and sends it to the Case Owner, who decides. This step shows that a suggestion goes to the Case Owner and does not admit Vendor2 by itself.
Extends: DEMOMA-10-004
Depends on: CM-20-003
DEMOMA-10-005 MUST Vendor1 MUST approve the Coordinator's suggestion of Vendor2.

The Case Owner decides who joins the case. This step shows that a suggestion becomes an invitation only after the Case Owner approves it.

ECA Details

Preconditions

- Vendor1 DataLayer holds pending Offer(CaseParticipant) for Vendor2 (DEMOMA-10-004 complete); Vendor2 container running

Steps

1. [vendor1] POST accept-actor-recommendation trigger for Vendor2 → Vendor1 accepts Offer(CaseParticipant); CaseActor sends Invite(VulnerabilityCase preview)[target=Actor], the stub carrying the embargo, to Vendor2
2. [demo-script] Poll Vendor2 DataLayer until Invite(VulnerabilityCase preview)[target=Actor] is visible → Invite activity present in Vendor2 DataLayer

Postconditions

- Vendor2 holds an invitation to the case; scenario may advance to Vendor2 acceptance

DEMOMA-10-014 MUST After Vendor1 approves the suggestion, the CaseActor MUST send Invite(VulnerabilityCase preview)[target=Actor], whose stub carries the embargo, to Vendor2 on Vendor1's behalf.

The CASE_MANAGER sends the invitation that the Case Owner approved. The invitation carries the embargo, so Vendor2 learns the terms before it joins.
Depends on: DEMOMA-10-005
Refines: CM-17-001
DEMOMA-10-006 MUST The RVCV-extension scenario MUST reach a final state with four participants, Reporter, Vendor1, Coordinator and Vendor2, plus the CaseActor.

The final state shows that every participant took part in the whole run, including Vendor2, which joined late.
DEMOMA-10-015 MUST The RVCV-extension scenario MUST advance to VFDPxa CS with EM.EXITED and RM.CLOSED for all participants.

The final state shows that the complete lifecycle ran for every participant. A run that ends with a participant that is not RM.CLOSED, or with the embargo still active, has not finished the scenario.
Extends: DEMOMA-10-006
DEMOMA-10-007 MUST The RVCV-extension scenario MUST run deterministically end to end.

A run that is not deterministic gives a verdict that does not depend only on the code.
DEMOMA-10-016 MUST The RVCV-extension scenario script MUST verify LedgerFanout replica convergence for Reporter, Coordinator and Vendor2 replicas against the authoritative Vendor1 state after each major protocol event.

Reporter, Coordinator and Vendor2 each hold a replica that must follow the canonical state. A check after each major event finds the first update that did not reach a replica.
DEMOMA-10-008 MUST The implementation of the RVCV-extension scenario MUST register it with the scenario registry (DEMOCI-11-001). Its generated .github/demo-scenarios.json entry (DEMOCI-11-004) then runs it as its own CI matrix job, concurrently with the other scenarios' jobs.

A scenario that does not run in CI can break without notice. A separate concurrent job keeps its failures visible on their own. It also keeps the elapsed time of a CI run close to the time of the slowest scenario. The matrix is generated from the registry, so registration is the only step (ADR-0098).
Refines: DEMOCI-11-001
See also: DEMOCI-11-004 — descriptive: names the registration the scenario then has
DEMOMA-10-017 MUST The RVCV-extension scenario MUST run end to end from a single orchestration command, such as docker compose.

A single command lets a developer run the same scenario in the same way that CI runs it.
Extends: DEMOMA-10-007
DEMOMA-10-009 MUST The Vendor1 actor container MUST set VULTRON_ACTOR__CASE_ACTOR_SERVICE_URL in its Docker Compose environment to the base URL of the dedicated CaseActor container, such as http://case-actor:7999/api/v2.

In a multi-container scenario the CaseActor runs in its own container, so its URL is not the URL of Vendor1. Without the variable, the case setup nodes return FAILURE and no case is created (CP-08-003).
Refines: CP-08-003
Implements: DEMOMA-10-019
DEMOMA-10-018 MUST In the RVCV-extension scenario, the case setup nodes MUST derive case_actor_id from the configured case_actor_service_url, not from server_base_url (CP-08-001 through CP-08-003).

The case setup nodes read the URL through case_actor_identity() and return FAILURE when it is not set. An identity derived from server_base_url would name an actor in the Vendor1 container that does not exist, so messages to it would fail or go to the wrong place (CP-08-003).
Depends on: DEMOMA-10-009
Depends on: CP-08-001
Depends on: CP-08-003
DEMOMA-10-010 MUST The RVCV-extension story MUST start with the shared "the Vendor invites a Coordinator" opening and continue from Vendor1's decision to keep the case.

The opening is the Reporter telling Vendor1, Vendor1 engaging the case and answering the Reporter's question, and Vendor1 inviting the Coordinator, which joins. The shared "the Vendor answers the Reporter" opening is nested inside the one DEMOMA-09-007 names and inside this one, so every vendor-first scenario tells it identically, and RVCV-handoff tells the whole of this one identically (DEMOMA-11-015). One copy of the code, so the recordings are byte-identical to where each pair's paths part (DEMOCI-11-018).
Refines: DEMOMA-17-001

RVCV-Handoff Scenario (Vendor1 hands ownership to Coordinator; it invites Vendor2)

Trigger: Scenario Start — rvcv-handoff

ID Priority Requirement Related
DEMOMA-11-001 MUST The RVCV-handoff scenario MUST involve four actor identities with isolated DataLayers and a separate CaseActor container, as DEMOMA-10-001 and DEMOMA-10-019 require.

The RVCV-handoff scenario must keep the same separation as RVCV-extension. Then the two scenarios differ in their protocol steps and not in their topology. A difference in their results then points to the ownership transfer and the steps that follow it.
Uses definition from: DEMOMA-10-001
Uses definition from: DEMOMA-10-019
DEMOMA-11-002 MUST Vendor1 MUST transfer case ownership to the Coordinator via the offer-case-ownership-transfer / accept-case-ownership-transfer handshake.

This is the defining contrast with RVCV-extension (DEMOMA-10-002): ownership transfers mid-scenario rather than staying with Vendor1 throughout. The Coordinator must already hold a case replica before accepting ownership, because AcceptCaseOwnershipTransferNode reads the case from the DataLayer and returns FAILURE if the case is not found.

ECA Details

Preconditions

- Vendor1 RM state = ACCEPTED; Coordinator is an existing signatory participant with a seeded case replica in their DataLayer; no pending ownership-transfer offer exists

Steps

1. [vendor1] POST offer-case-ownership-transfer trigger targeting Coordinator → Vendor1's proposal queued for the CASE_MANAGER, which queues its Offer(VulnerabilityCase) for the Coordinator inbox
2. [demo-script] Poll Coordinator DataLayer until Offer(VulnerabilityCase) is visible → Offer activity present in Coordinator DataLayer
3. [coordinator] POST accept-case-ownership-transfer trigger → Coordinator CVDRole updated to CASE_OWNER; Vendor1 role updated to plain participant; VulnerabilityCase attributed_to updated to Coordinator actor ID

Postconditions

- Coordinator holds CVDRole.CASE_OWNER; Vendor1 is a plain participant; VulnerabilityCase.attributed_to = Coordinator actor ID; all participants' case replicas reflect the updated ownership

Depends on: TRIG-11-001
Depends on: TRIG-11-002
DEMOMA-11-003 MUST After it becomes CASE_OWNER, the Coordinator MUST invite Vendor2 directly with the invite-actor-to-case trigger.

In RVCV-extension, Vendor1 approves a Coordinator suggestion. In RVCV-handoff, the Coordinator is the owner and invites directly, so no approval step is needed.

ECA Details

Preconditions

- Coordinator holds CVDRole.CASE_OWNER (DEMOMA-11-002 complete); Vendor2 container running; no existing Invite for Vendor2 in the case

Steps

1. [coordinator] POST invite-actor-to-case trigger for Vendor2 → CaseActor queues Invite(VulnerabilityCase preview)[target=Actor] for Vendor2
2. [demo-script] Poll Vendor2 DataLayer until Invite(VulnerabilityCase preview)[target=Actor] is visible → Invite activity present in Vendor2 DataLayer
3. [vendor2] POST accept-case-invite trigger directed to CaseActor → Vendor2 joins the case and becomes a signatory (active); CaseActor emits Announce(VulnerabilityCase) to seed Vendor2 case replica
4. [demo-script] Poll Vendor2 DataLayer until case replica is seeded → VulnerabilityCase record present in Vendor2 DataLayer

Postconditions

- Vendor2 is a signatory participant with a seeded case replica; scenario may advance to fix tracking and final state

DEMOMA-11-021 MUST In the RVCV-handoff scenario, Vendor2 MUST accept the Coordinator's invitation before the scenario advances.

An Invite alone does not seed the replica (MV-10-004). The CaseActor's Announce fires only after the stub Invite is accepted (CM-11-008), so the scenario cannot go on until Vendor2 accepts.
Extends: DEMOMA-11-003
DEMOMA-11-004 MUST VulnerabilityCase.attributed_to MUST name the Coordinator's actor ID after the ownership transfer completes.

attributed_to names the Case Owner, and owner checks such as is_case_owner compare an actor with it. If it keeps the old value after the transfer, the previous owner is still treated as the Case Owner.
DEMOMA-11-016 MUST All participants MUST observe the updated attributed_to in their case replicas after the RVCV-handoff ownership transfer.

Owner checks such as is_case_owner read attributed_to in the local replica. A replica that keeps the old value refuses owner acts from the new Case Owner, and it judges the authority of other participants wrongly.
Depends on: DEMOMA-11-004
DEMOMA-11-005 MUST An active embargo initiated before an ownership transfer MUST remain ACTIVE through and after the transfer.

An ownership transfer changes who runs the case. It does not change the terms that the participants agreed to. If the transfer ended or reset the embargo, a change of the Case Owner could release information early. Each party relies on the embargo staying in force.
Refines: DEMOMA-11-017
DEMOMA-11-017 MUST The EM state machine MUST transition correctly through the ownership change of the RVCV-handoff scenario.

The transfer happens while the embargo is in force. An EM transition that fails or skips a state at that point would leave the participants with an embargo state that no protocol step produced.
DEMOMA-11-006 MUST The RVCV-handoff scenario MUST reach a final state with four participants, Reporter, Vendor1, Coordinator and Vendor2, plus the CaseActor (DEMOMA-10-006).

The final state shows that every participant is still in the case after the ownership transfer.
See also: DEMOMA-10-006 — a sibling scenario's rule ("as ... requires")
DEMOMA-11-018 MUST The RVCV-handoff scenario MUST advance to VFDPxa CS with EM.EXITED and RM.CLOSED for all participants, as DEMOMA-10-015 requires.

The final state shows that the lifecycle completes after the ownership transfer. A transfer that left a participant unable to reach RM.CLOSED, or left the embargo active, would show in this check.
Extends: DEMOMA-11-006
See also: DEMOMA-10-015 — a sibling scenario's rule ("as ... requires")
DEMOMA-11-007 MUST The RVCV-handoff scenario MUST run deterministically, as DEMOMA-10-007 requires.

A deterministic run gives a verdict that depends only on the code, before and after the ownership changes.
See also: DEMOMA-10-007 — a sibling scenario's rule ("as ... requires")
DEMOMA-11-019 MUST The RVCV-handoff scenario MUST verify LedgerFanout replica convergence for all non-owning participants after each major protocol event, as DEMOMA-10-016 requires.

After the transfer, every participant that is not the Case Owner must still receive canonical updates. A check after each major event finds the first update that a replica did not receive, before or after the ownership changes.
See also: DEMOMA-10-016 — a sibling scenario's rule ("as ... requires")
DEMOMA-11-008 MUST The implementation of the RVCV-handoff scenario MUST register it with the scenario registry (DEMOCI-11-001), as DEMOMA-10-008 requires.

A scenario that does not run in CI can break without notice, and a scenario that cannot be started from the CLI is hard to run and debug locally. Registration gives the scenario its own CI matrix job (DEMOCI-11-004) and its CLI sub-command (DEMOCI-11-011), so no workflow or cli.py edit is needed (ADR-0098).
Refines: DEMOCI-11-001
See also: DEMOMA-10-008 — a sibling scenario's rule ("as ... requires")
DEMOMA-11-009 MUST The RVCV-handoff scenario script MUST include polling wait steps at each asynchronous protocol boundary before driving the next trigger.

A trigger commits its local change and then returns. The outbox is sent after the response, and the receiving actor commits its own change later, in another container. If the script drives the next trigger before that change is visible to the target actor, the trigger runs on state that does not exist yet. The run then fails, or it passes only when the timing is fortunate. This requirement applies the general rule DEMOMA-22-001 to RVCV-handoff (ADR-0058).

ECA Details

Preconditions

- RVCV-handoff scenario executing; Vendor1 has just emitted the ownership-transfer offer and the script is driving subsequent async steps

Steps

1. [demo-script] After emitting the ownership-transfer offer: poll Coordinator's DataLayer until Offer(VulnerabilityCase) is visible → Offer activity present in Coordinator DataLayer
2. [demo-script] After Coordinator accepts the offer: poll Vendor1's case replica until attributed_to reflects the Coordinator's actor ID → Vendor1 case replica shows VulnerabilityCase.attributed_to = Coordinator actor ID
3. [demo-script] After Coordinator invites Vendor2: poll Vendor2's DataLayer until Invite(VulnerabilityCase preview)[target=Actor] is visible → Invite activity present in Vendor2 DataLayer
4. [demo-script] After Vendor2 accepts the invitation: poll Vendor2's DataLayer until the case replica seeded by CaseActor's Announce(VulnerabilityCase) is present → VulnerabilityCase record present in Vendor2 DataLayer

Postconditions

- All four async boundaries confirmed; each actor's DataLayer reflects the expected state before the next trigger is driven; scenario proceeds deterministically

Derives from: DEMOMA-22-001 — A polling wait at each RVCV-handoff boundary follows from DEMOMA-22-001, which gates every async boundary of every scenario and also constrains what the wait may observe (EDF-06-001 through EDF-06-003). Meeting this requirement does not meet DEMOMA-22-001: "a polling wait exists here" is necessary but not sufficient. This requirement remains active; it is not superseded.
DEMOMA-11-010 MUST The Vendor1 actor container MUST set VULTRON_ACTOR__CASE_ACTOR_SERVICE_URL in its Docker Compose environment to the base URL of the dedicated CaseActor container, such as http://case-actor:7999/api/v2.

In a multi-container scenario the CaseActor runs in its own container, so its URL is not the URL of Vendor1. Without the variable, the case setup nodes return FAILURE and no case is created (CP-08-003).
Refines: CP-08-003
DEMOMA-11-020 MUST In the RVCV-handoff scenario, the case setup nodes MUST derive case_actor_id from the configured case_actor_service_url, not from server_base_url (CP-08-001 through CP-08-003).

The case setup nodes read the URL through case_actor_identity() and return FAILURE when it is not set. An identity derived from server_base_url would name an actor in the Vendor1 container that does not exist, so messages to it would fail or go to the wrong place (CP-08-003).
Depends on: DEMOMA-11-010
Depends on: CP-08-001
Depends on: CP-08-003
DEMOMA-11-011 MUST After the RVCV-handoff ownership transfer, the Coordinator MUST hold CVDRole.CASE_OWNER.

The ownership transfer postcondition for the Coordinator: it becomes the Case Owner.
DEMOMA-11-012 MUST The CaseActor MUST seed Vendor2's case replica on Vendor2's acceptance of the RVCV-handoff invitation.

Replica seeding is the CaseActor's responsibility after each new participant accepts an invitation.
DEMOMA-11-013 MUST All participants (including Vendor2 after joining) MUST be subject to an active embargo that was established before the RVCV-handoff ownership transfer.

Ownership transfer does not alter PEC consent rows; all prior signatories and any late-joining participants remain bound by the active embargo.
DEMOMA-11-014 MUST After the RVCV-handoff ownership transfer, Vendor1 MUST become a plain participant (no longer holding CVDRole.CASE_OWNER).

The ownership transfer postcondition for Vendor1: it relinquishes the Case Owner role and becomes an ordinary participant.
DEMOMA-11-015 MUST The RVCV-handoff story MUST start with the same shared opening as RVCV-extension (DEMOMA-10-010) and continue from Vendor1's decision to offer ownership.

The two scenarios part at one decision, so everything before it is one copy of the code and their recordings are byte-identical up to the owner-keep-case branch point (DEMOCI-11-018). It also makes the Coordinator an active participant holding the coordinating role before the transfer is offered, which CM-21-021 requires. Naming it here keeps this group a whole story.
Refines: DEMOMA-17-001
Uses definition from: DEMOMA-10-010

RCV Scenario (Reporter reports to Coordinator; Coordinator invites Vendor)

Trigger: Scenario Start — rcv

ID Priority Requirement Related
DEMOMA-12-001 MUST The RCV scenario MUST involve four actor identities, Reporter, Coordinator, Vendor and CaseActor, each with its own isolated DataLayer and separate container.

RCV is the canonical three-party coordination baseline. Using four separate containers (Reporter, Coordinator, Vendor, CaseActor) matches the RVCV-extension topology (DEMOMA-10-001) and ensures the demo exercises true multi-container message delivery rather than in-process calls.
Refines: DEMOMA-01-001
DEMOMA-12-019 MUST In the RCV scenario, the CaseActor MUST run as a separate actor identity with its own container and DataLayer, not on the Coordinator container.

The Coordinator is the Case Owner and the CaseActor holds CASE_MANAGER. A CaseActor on the Coordinator container could share state with the Coordinator by a path that the protocol does not have, so the demo could pass although the messages between them are missing.
Extends: DEMOMA-12-001
DEMOMA-12-002 MUST The Coordinator MUST receive the Reporter's report (RM→RECEIVED), validate it (RM→VALID), and engage the case (RM→ACCEPTED). Engagement triggers CaseActor creation on the CaseActor's own container (DEMOMA-12-019).

RCV is the scenario in which the Coordinator is the Case Owner: the Reporter reports to the Coordinator, and the Coordinator creates the case. In RVV and RVCV-extension the Vendor is the Case Owner. The Coordinator holds CASE_OWNER, and the CaseActor in its own container holds CASE_MANAGER (DEMOMA-12-019).

ECA Details

Preconditions

- All four containers running (Reporter, Coordinator, Vendor, CaseActor); no VulnerabilityCase exists for this report; Coordinator auto_create_case=True; Coordinator pre-configured with the dedicated CaseActor container URL

Steps

1. [reporter] POST submit-report trigger directed at Coordinator → Report delivered to Coordinator inbox
2. [coordinator] BT processes inbound report; RM transitions RECEIVED→VALID→ACCEPTED → VulnerabilityCase created; CaseActor registered on the separate CaseActor container (not co-located on the Coordinator container, per DEMOMA-12-019); default embargo initialized to EM.ACTIVE (EP-04-001); EM.ACTIVE is established at case creation before any participant invitation
3. [coordinator] Coordinator assigned CVDRole.CASE_OWNER on the new case → Coordinator holds CASE_OWNER; CaseActor holds CASE_MANAGER
4. [coordinator] Coordinator sends trust-bootstrap Create(VulnerabilityCase) to Reporter (CBT-01-001); Reporter is the original report submitter so MUST receive this one-time bootstrap to trust the CaseActor identity → Reporter receives Create(VulnerabilityCase) carrying Coordinator as CASE_OWNER and CaseActor as COORDINATOR; Reporter trusts CaseActor for this case

Postconditions

- VulnerabilityCase exists; Coordinator RM=ACCEPTED, CVDRole=CASE_OWNER; CaseActor running with CASE_MANAGER on its own container; EM.ACTIVE established; trust bootstrap delivered to Reporter; no ownership transfer has occurred

Uses definition from: DEMOMA-12-019
DEMOMA-12-003 MUST NOT The Coordinator MUST NOT invite the Reporter to the case.

The Reporter is the reporter, so the CASE_MANAGER seats it as a signatory participant when it creates the case (CP-09-002, CM-14-005). The reporter's consent is implicit in submitting the report (CM-14-005), so an Invite/Accept exchange for the Reporter would record an invitation that never occurred (CM-18-003).
Derives from: CP-09-002
DEMOMA-12-020 MUST Before the Vendor is invited, the RCV scenario MUST confirm that the Reporter is a participant and holds a case replica.

The Reporter is seated when the case is created, with no invitation to wait on. A check before the Vendor's invitation shows that the seating and the Reporter's replica exist before the scenario moves on.

ECA Details

Preconditions

- DEMOMA-12-002 postconditions satisfied: VulnerabilityCase exists, Coordinator RM=ACCEPTED, CVDRole=CASE_OWNER, EM.ACTIVE, trust bootstrap Create(VulnerabilityCase) already delivered to Reporter (CBT-01-001)

Steps

1. [demo_script] Wait until the Coordinator's case lists the Reporter and the Coordinator as participants → Reporter present as a participant seated at case creation, with no Invite/Accept exchange (the case-actor log's single invite_actor_to_case entry, the Vendor's, is checked by DEMOMA-12-009(2))
2. [demo_script] Verify the case is active and the Reporter holds a case replica → Reporter holds a case replica with EM.ACTIVE

Postconditions

- Reporter is a signatory with a case replica; Vendor invitation has not yet been issued

DEMOMA-12-004 MUST The Coordinator MUST invite the Vendor to the case with the invite-actor-to-case trigger directly, not through a suggestion and approval chain.

Coordinator is CASE_OWNER, so a direct invite-actor-to-case is correct; the ADR-0026 suggest/approve chain is for participants recommending actors to the Case Owner, not for the owner inviting directly.

ECA Details

Preconditions

- Reporter is a signatory with a case replica (DEMOMA-12-020 postconditions satisfied); Vendor is not yet a case participant

Steps

1. [coordinator] POST invite-actor-to-case trigger for Vendor → Invite(VulnerabilityCase preview)[target=Actor] delivered to Vendor inbox
2. [demo_script] Poll Vendor DataLayer until Invite(VulnerabilityCase preview)[target=Actor] is visible → Invitation record present in Vendor replica
3. [vendor] POST accept-case-invite trigger → Vendor becomes a signatory; CaseActor emits Announce(VulnerabilityCase) to seed Vendor replica with full case history

Postconditions

- Vendor is a signatory with a seeded case replica containing full history from genesis; all three actors (Reporter, Coordinator, Vendor) plus CaseActor are now case participants

DEMOMA-12-021 MUST In the RCV scenario, the Vendor MUST accept the invitation with the accept-case-invite trigger.

The Vendor joins through its own trigger, so its own behavior tree decides and acts. Polling before accept is required for determinism (per DEMOMA-11-009 pattern).
Extends: DEMOMA-12-004
DEMOMA-12-005 MUST The RCV scenario MUST reach a final state with three participants — Reporter, Coordinator, and Vendor (plus the CaseActor) — advancing to VFDPxa CS with EM.EXITED and RM.CLOSED for all participants; only Vendor's fix path (VFD) is tracked.

RCV has one Vendor, so only that Vendor has a fix path. The final state shows that the complete lifecycle ran for all three parties. The Coordinator and Reporter have no fix path, so a check on their fix path state would test nothing.
DEMOMA-12-006 MUST The RCV scenario MUST run deterministically end to end.

A deterministic run gives a verdict that depends only on the code.
DEMOMA-12-022 MUST The RCV scenario MUST verify LedgerFanout replica convergence for Reporter and Vendor replicas against the authoritative Coordinator/CaseActor state after each major protocol event.

The Reporter and Vendor replicas must follow the canonical state. A check after each major event finds the first update that did not reach a replica.
DEMOMA-12-007 MUST The implementation of the RCV scenario MUST register it with the scenario registry (DEMOCI-11-001) in the same PR, so that its generated .github/demo-scenarios.json entry (DEMOCI-11-004) runs it as its own CI matrix job and CI failures are independently reported per DEMOCI-03-003.

A scenario that is not registered has no entry in the CI matrix, so it can break without notice. Registration in the same pull request gives the scenario a matrix entry from the time that it is in the repository. Its own CI job keeps its failures separate from those of other scenarios (DEMOCI-03-003).
Refines: DEMOCI-03-002
Refines: DEMOCI-11-001
See also: DEMOCI-03-003 — the consequence the statement cites (independent reporting), not a link
See also: DEMOCI-11-004 — descriptive: names the registration the scenario then has
DEMOMA-12-008 MUST The RCV implementation MUST ship a dedicated per-scenario case-ledger invariant test file (test/ci/invariants/test_rcv_invariants.py) built exclusively on the shared invariant library introduced by the harness refactor (issue #1592); DEMOMA-12-008 is satisfied only when that shared library exists.

Requiring use of the shared library enforces the DRY constraint across scenarios. A file that copies invariant logic is not compliant even if it tests the correct things.
DEMOMA-12-009 MUST The RCV per-scenario invariant test file MUST assert the following scenario-specific checks in addition to the universal library checks: (1) validate_report event present in case-actor log, (2) invite_actor_to_case present exactly once (the Vendor invitation; the Reporter is seated, not invited, per DEMOMA-12-003), (3) close_case present, (4) CS transitions VFd and VFD observed in add_participant_status_to_participant entries for the Vendor actor and public-aware (P) transition observed in add_participant_status_to_participant entries for the Coordinator actor, and (5) Vendor replica holds the complete log from genesis (full history backfill, as Vendor is a late joiner).

Scenario-specific invariants prevent the RCV scenario from accidentally omitting protocol steps not covered by universal checks. Explicitly enumerating them here means CI will catch regressions in the steps unique to RCV.
Extends: DEMOMA-12-008
Verifies: DEMOMA-12-003
DEMOMA-12-010 MUST The Coordinator actor container MUST set VULTRON_ACTOR__CASE_ACTOR_SERVICE_URL in its Docker Compose environment to the base URL of the dedicated CaseActor container, such as http://case-actor:7999/api/v2.

In a multi-container scenario the CaseActor runs in its own container, so its URL is not the URL of Coordinator. Without the variable, the case setup nodes return FAILURE and no case is created (CP-08-003).
Refines: CP-08-003
Implements: DEMOMA-12-019
DEMOMA-12-023 MUST In the RCV scenario, the case setup nodes MUST derive case_actor_id from the configured case_actor_service_url, not from server_base_url (CP-08-001 through CP-08-003).

The case setup nodes read the URL through case_actor_identity() and return FAILURE when it is not set. An identity derived from server_base_url would name an actor in the Coordinator container that does not exist, so messages to it would fail or go to the wrong place (CP-08-003).
Depends on: DEMOMA-12-010
Depends on: CP-08-001
Depends on: CP-08-003
DEMOMA-12-011 MUST The Coordinator MUST keep CVDRole.CASE_OWNER for the whole RCV scenario, with no transfer of ownership to any other actor.

RCV is the canonical Coordinator-as-owner scenario. Retaining CASE_OWNER throughout differentiates it from RVCV-extension and RVCV-handoff variants.
DEMOMA-12-012 MUST The CaseActor MUST emit Announce(VulnerabilityCase) to seed Vendor's case replica after Vendor accepts the invitation in the RCV scenario.

Replica seeding via Announce is the CaseActor's canonical response to an accepted invitation (PCR-02-002).
DEMOMA-12-013 MUST The RCV demo script MUST poll Vendor's DataLayer for the arriving invitation before driving the accept step.

Polling before accept is required for determinism; driving accept before the invitation is visible in Vendor's DataLayer causes a race condition.
DEMOMA-12-014 MUST RCV demo scripts MUST verify EM.ACTIVE at the case-creation milestone and EM.EXITED at the final milestone.

The causal chain EM.ACTIVE (established at case creation per EP-04-001) to EM.EXITED (triggered by CS.P per DEMOMA-07-003(4)) must be confirmed at both endpoints.
DEMOMA-12-015 MUST NOT The RCV invariant test file MUST NOT duplicate universal invariant logic.

Universal invariants are the same for every scenario, so the shared library keeps them in one place. A copy in the RCV test file can drift from the library. Then a defect fixed in the library stays in RCV, or RCV checks a weaker rule than every other scenario does.
DEMOMA-12-024 MUST The RCV invariant test file MUST import the universal chain, hash and RM-closed checks from the shared library, not re-implement them inline.

The import is how the RCV file uses the one copy of each universal check. A check written inline is a second copy that can drift from the library.
Implements: DEMOMA-12-015
DEMOMA-12-016 MUST The P-set CS state MUST be visible in all replicas via Add(CaseLedgerEntry) fan-out after the Coordinator triggers CS.P.

Add(CaseLedgerEntry) is the sole canonical propagation path for status updates to peers (SYNC-02-001, SYNC-02-003); this invariant confirms the fan-out fired.
DEMOMA-12-017 MUST The RCV story MUST start with the shared "the Coordinator invites the Vendor" opening and continue from the Vendor's acceptance.

The opening is the Reporter telling the Coordinator, the Coordinator engaging the case, and the Coordinator inviting the Vendor. RCV tells it identically to RCV-reject, so it is one copy of the code and the recordings of the two are byte-identical up to the Vendor's decision (DEMOCI-11-018). Naming it here keeps this group a whole story: a reader sees where RCV's own telling begins without reading the sibling's group.
Refines: DEMOMA-17-001
DEMOMA-12-018 MUST The RCV story MUST carry on from the shared "the Coordinator invites the Vendor" opening. It continues through the Vendor's acceptance, the replica convergence and the answered note thread.

Those three steps are told identically by RCVCV (DEMOMA-19-024), so they are one further stretch of shared code and the two recordings are byte-identical to the coordinator-after-answer branch point (DEMOCI-11-018). Naming the longer stretch as its own requirement leaves DEMOMA-12-017's shorter opening, which RCV-reject also starts with (DEMOMA-27-004), obliging exactly what it always did.
Refines: DEMOMA-12-017

RCCV-Extension Scenario (C1 retains ownership; C2 is participant; C2 suggests Vendor)

Trigger: Scenario Start — rccv-extension

ID Priority Requirement Related
DEMOMA-13-001 MUST The RCCV-extension scenario MUST involve four actor identities, Reporter, Coordinator1 (C1), Coordinator2 (C2) and Vendor, each with its own isolated DataLayer.

RCCV-extension demonstrates inter-coordinator collaboration: C1 is the Case Owner, C2 is a participating coordinator who can suggest new actors but cannot independently invite them. The topology is the same as RVCV-extension (DEMOMA-10-001) with the C1 role replacing Vendor1 as Case Owner.
Refines: DEMOMA-01-001
DEMOMA-13-013 MUST In the RCCV-extension scenario, the CaseActor MUST run as a separate actor identity with its own container and DataLayer, not in the C1 container.

The five-container topology (Reporter, C1, C2, Vendor, CaseActor) keeps the CaseActor apart from the Case Owner. A CaseActor in the C1 container could share state with C1 by a path that the protocol does not have.
Extends: DEMOMA-13-001
DEMOMA-13-002 MUST C1 MUST receive the Reporter's report (RM→RECEIVED), validate it (RM→VALID), and engage the case (RM→ACCEPTED).

C1 is the initial report recipient. It engages the case and so becomes the Case Owner, which the rest of the scenario relies on.

ECA Details

Preconditions

- All five containers running (Reporter, C1, C2, Vendor, CaseActor); no VulnerabilityCase exists for this report; C1 auto_create_case=True; C1 pre-configured with the dedicated CaseActor container URL

Steps

1. [reporter] POST submit-report trigger directed at C1 → Report delivered to C1 inbox
2. [c1] BT processes inbound report; RM transitions RECEIVED→VALID→ACCEPTED → VulnerabilityCase created; CaseActor registered on the separate CaseActor container; default embargo initialized to EM.ACTIVE (EP-04-001)
3. [c1] C1 assigned CVDRole.CASE_OWNER on the new case → C1 holds CASE_OWNER; CaseActor holds CASE_MANAGER
4. [c1] C1 sends trust-bootstrap Create(VulnerabilityCase) to Reporter (CBT-01-001); Reporter is the original report submitter and MUST receive this bootstrap to trust the CaseActor identity → Reporter receives Create(VulnerabilityCase) carrying C1 as CASE_OWNER and CaseActor as COORDINATOR; Reporter trusts CaseActor for this case

Postconditions

- VulnerabilityCase exists; C1 RM=ACCEPTED, CVDRole=CASE_OWNER; CaseActor running with CASE_MANAGER on its own container; EM.ACTIVE established; trust bootstrap delivered to Reporter; Reporter is an initial participant via the report-submission bootstrap (not via a separate invite-actor-to-case trigger); no ownership transfer has occurred

DEMOMA-13-014 MUST C1 MUST keep CVDRole.CASE_OWNER for the whole RCCV-extension scenario, with no transfer of ownership to C2 or the Vendor.

This scenario demonstrates the "extension" variant where a Coordinator creates and owns a case. C1 is the authority that approves all participant additions, in contrast to the RVCV-extension variant where a Vendor holds ownership.
Extends: DEMOMA-13-002
DEMOMA-13-003 MUST In the RCCV-extension scenario, C2 MUST accept C1's invitation and join the case as a participant that holds CVDRole.COORDINATOR, not CVDRole.CASE_MANAGER.

C2 must be a participant before it can suggest a vendor. CASE_MANAGER is the role that commits canonical case state, and in this scenario the CaseActor holds it. If C2 also held CASE_MANAGER, two actors could commit case changes, and the scenario would not show a coordinator that participates without control.

ECA Details

Preconditions

- DEMOMA-13-002 postconditions satisfied: C1 RM=ACCEPTED, CVDRole=CASE_OWNER; EM.ACTIVE; trust bootstrap delivered to Reporter; Reporter is an initial participant; C2 container running

Steps

1. [c1] POST invite-actor-to-case trigger targeting C2 → CaseActor queues Invite(VulnerabilityCase preview)[target=Actor] for C2's inbox
2. [demo-script] Poll C2 DataLayer until Invite(VulnerabilityCase preview)[target=Actor] is visible → Invite activity present in C2 DataLayer
3. [c2] POST accept-case-invite trigger → C2 joins the case (active) with CVDRole.COORDINATOR (not CASE_MANAGER); CaseActor seeds C2 case replica

Postconditions

- C2 is a participant with CVDRole.COORDINATOR and NOT CVDRole.CASE_MANAGER; C2 holds a seeded case replica; case has four participants (Reporter, C1, C2, CaseActor)

Refines: CM-20-001
DEMOMA-13-015 MUST In the RCCV-extension scenario, C1 MUST invite C2 to the case.

C1 is the Case Owner, so it decides who joins the case. C2 joins only through an invitation from C1.
Extends: DEMOMA-13-003
DEMOMA-13-004 MUST In the RCCV-extension scenario, C2 MUST suggest the Vendor to the case.

C2 is not the Case Owner, so it cannot add a party to the case. It can only suggest one. This step drives that suggestion through C2's own trigger.

ECA Details

Preconditions

- C2 is an accepted participant (DEMOMA-13-003 complete); Vendor container running; no existing suggestion for Vendor in the case

Steps

1. [c2] POST suggest-actor-to-case trigger for Vendor with roles=["vendor"] → C2 sends Offer(Actor)[target=VulnerabilityCase] to CaseActor inbox
2. [case-actor] Transform Offer(Actor)[target=VulnerabilityCase] to Offer(CaseParticipant)[target=VulnerabilityCase] naming Vendor with roles [vendor] → Transformed offer forwarded to C1 (Case Owner) inbox
3. [demo-script] Poll C1 DataLayer until transformed Offer(CaseParticipant) is visible → Transformed offer present in C1 DataLayer

Postconditions

- C1 holds a pending Offer(CaseParticipant) for Vendor awaiting approval; no invitation has been sent to Vendor yet

Uses definition from: CM-16-001
DEMOMA-13-016 MUST The CaseActor MUST transform C2's suggestion of the Vendor and forward it to C1 for approval.

The CASE_MANAGER changes the suggestion into an Offer(CaseParticipant) and sends it to C1, who decides. This step shows that a suggestion from a coordinator goes to the Case Owner and does not admit the Vendor by itself.
Extends: DEMOMA-13-004
Depends on: CM-20-003
DEMOMA-13-005 MUST C1 MUST approve C2's suggestion of the Vendor.

The Case Owner decides who joins the case. This step shows that a suggestion becomes an invitation only after C1 approves it.

ECA Details

Preconditions

- C1 DataLayer holds pending Offer(CaseParticipant) for Vendor (DEMOMA-13-004 complete); Vendor container running

Steps

1. [c1] POST accept-actor-recommendation trigger for Vendor → C1 accepts Offer(CaseParticipant); CaseActor sends Invite(VulnerabilityCase preview)[target=Actor], the stub carrying the embargo, to Vendor
2. [demo-script] Poll Vendor DataLayer until Invite(VulnerabilityCase preview)[target=Actor] is visible → Invite activity present in Vendor DataLayer
3. [vendor] POST accept-case-invite trigger → Vendor joins the case (active) with CVDRole.VENDOR; CaseActor seeds Vendor case replica with full history

Postconditions

- Vendor is a participant with CVDRole.VENDOR and a seeded case replica; all five participants present (Reporter, C1, C2, Vendor, CaseActor)

DEMOMA-13-017 MUST After C1 approves the suggestion, the CaseActor MUST send Invite(VulnerabilityCase preview)[target=Actor], whose stub carries the embargo, to the Vendor on C1's behalf.

The CASE_MANAGER sends the invitation that the Case Owner approved. The invitation carries the embargo, so the Vendor learns the terms before it joins.
Depends on: DEMOMA-13-005
Refines: CM-17-001
DEMOMA-13-006 MUST The RCCV-extension scenario MUST reach a final state with four participants, Reporter, C1, C2 and Vendor, plus the CaseActor.

The final state shows that every participant took part in the whole run, including the Vendor, which joined late.
DEMOMA-13-018 MUST The RCCV-extension scenario MUST advance to VFDPxa CS with EM.EXITED and RM.CLOSED for all participants.

Only Vendor tracks a vendor fix path (VFD). C1 and C2 hold CVDRole.COORDINATOR and have no VFD substate. Reporter has no VFD substate. EM.EXITED is triggered by CS.P (public disclosure). C1 (CASE_OWNER) is the actor that triggers CS.P per DEMOMA-07-003(4).
Extends: DEMOMA-13-006
DEMOMA-13-007 MUST The RCCV-extension scenario MUST run deterministically end to end.

A deterministic run gives a verdict that depends only on the code.
DEMOMA-13-019 MUST The RCCV-extension scenario MUST verify LedgerFanout replica convergence for Reporter, C2 and Vendor replicas against the authoritative C1/CaseActor state after each major protocol event.

Each replica that is not the authority must follow the canonical state. A check after each major event finds the first update that did not reach a replica.
DEMOMA-13-008 MUST The implementation of the RCCV-extension scenario MUST register it with the scenario registry (DEMOCI-11-001), so that its generated .github/demo-scenarios.json entry (DEMOCI-11-004) runs it as its own CI matrix job and CI failures are independently reported per DEMOCI-03-003.

A scenario that is not registered does not run in CI, so it can break without notice. Its own CI job keeps its failures separate from those of other scenarios (DEMOCI-03-003).
Refines: DEMOCI-11-001
See also: DEMOCI-03-003 — the consequence the statement cites (independent reporting), not a link
See also: DEMOCI-11-004 — descriptive: names the registration the scenario then has
DEMOMA-13-009 MUST The RCCV-extension implementation MUST ship a dedicated per-scenario case-ledger invariant test file (test/ci/invariants/test_rccv_extension_invariants.py) built exclusively on the shared invariant library (per DEMOMA-12-008 pattern).

Scenario-specific invariants prevent the RCCV-extension scenario from accidentally omitting protocol steps not covered by universal checks. The Vendor-as-late-joiner invariant is shared with RVCV-extension (DEMOMA-10) and RCCV-handoff (DEMOMA-15).
See also: DEMOMA-12-008 — a sibling scenario's pattern ("per ... pattern")
DEMOMA-13-010 MUST The C1 actor container MUST set VULTRON_ACTOR__CASE_ACTOR_SERVICE_URL in its Docker Compose environment to the base URL of the dedicated CaseActor container, such as http://case-actor:7999/api/v2.

In a multi-container scenario the CaseActor runs in its own container, so its URL is not the URL of C1. Without the variable, the case setup nodes return FAILURE and no case is created (CP-08-003).
Refines: CP-08-003
Implements: DEMOMA-13-013
DEMOMA-13-020 MUST In the RCCV-extension scenario, the case setup nodes MUST derive case_actor_id from the configured case_actor_service_url, not from server_base_url (CP-08-001 through CP-08-003).

The case setup nodes read the URL through case_actor_identity() and return FAILURE when it is not set. An identity derived from server_base_url would name an actor in the C1 container that does not exist, so messages to it would fail or go to the wrong place (CP-08-003).
Depends on: DEMOMA-13-010
Depends on: CP-08-001
Depends on: CP-08-003
DEMOMA-13-011 MUST The RCCV-extension invariant test file MUST assert the following scenario-specific checks in addition to universal library checks: (1) validate_report event present in case-actor log, (2) invite_actor_to_case present at least twice (C2 invitation + Vendor invitation), (3) close_case present, (4) CS transition VFd observed in add_participant_status_to_participant entries for the Vendor actor and public-aware (P) transition observed in add_participant_status_to_participant entries for C1 (CASE_OWNER triggers CS.P), and (5) Vendor replica holds the complete log from genesis (full history backfill, as Vendor is a late joiner).

Scenario-specific invariants prevent the RCCV-extension scenario from accidentally omitting protocol steps not covered by universal checks.
DEMOMA-13-012 MUST The RCCV-extension story MUST start with the shared "C1 invites a second Coordinator" opening and continue from C1's decision to keep the case.

The opening is the Reporter telling C1, C1 engaging the case, and C1 inviting C2, which joins. The shared "the Reporter tells the Coordinator" opening is nested inside the one DEMOMA-12-017 names and inside this one, so every coordinator-first scenario tells it identically, and RCCV-handoff tells the whole of this one identically (DEMOMA-14-017). One copy of the code, so the recordings are byte-identical to where each pair's paths part (DEMOCI-11-018).
Refines: DEMOMA-17-001

RCCV-Handoff Scenario (C1 transfers case ownership to C2; C2 invites Vendor)

Trigger: Scenario Start — rccv-handoff

ID Priority Requirement Related
DEMOMA-14-001 MUST The RCCV-handoff scenario MUST involve four actor identities, Reporter, Coordinator1 (C1), Coordinator2 (C2) and Vendor, each with its own isolated DataLayer.

RCCV-handoff demonstrates the case-ownership-transfer flow between two coordinators. C1 starts as CASE_OWNER, then transfers ownership to C2 via TRIG-11-001/002. Its five containers come from the fixed cast: C1 in the first Coordinator slot, the Vendor in the first Vendor slot, C2 in a character-actor slot, plus the Reporter slot and the dedicated CaseActor container (DEMOCI-11-020).
Refines: DEMOMA-01-001
DEMOMA-14-018 MUST In the RCCV-handoff scenario, the CaseActor MUST run as a separate actor identity with its own container and DataLayer.

The CaseActor holds CASE_MANAGER through the ownership transfer, so its store must stay apart from both C1 and C2. Its dedicated container is the one the fixed cast reserves for it (DEMOCI-11-020).
Extends: DEMOMA-14-001
DEMOMA-14-002 MUST C1 MUST receive the Reporter's report (RM→RECEIVED), validate it (RM→VALID), and engage the case (RM→ACCEPTED), holding CVDRole.CASE_OWNER until it completes the ownership transfer to C2.

C1 is the first Case Owner, so this scenario tests the ownership transfer from a Coordinator. RVCV-handoff (DEMOMA-11) tests it from a Vendor. C1 becomes the Case Owner when it receives the report and creates the case. Only a Case Owner can offer the transfer, so these steps must come first.

ECA Details

Preconditions

- All five containers running (Reporter, C1, C2, Vendor, CaseActor); all actors seeded and cross-registered.

Steps

1. [reporter] POST submit-report trigger to C1 → C1 creates VulnerabilityCase; RM→RECEIVED on C1
2. [demo-script] POST validate-report and engage-case triggers on C1 → C1 RM→VALID then RM→ACCEPTED; C1 holds CVDRole.CASE_OWNER

Postconditions

- C1 holds CVDRole.CASE_OWNER and case attributed_to=C1.

DEMOMA-14-003 MUST C1 MUST invite C2 to the case (CVDRole.COORDINATOR).

C2 must be a known participant before C1 can offer ownership transfer. The invite-accept flow establishes C2's presence in the case ledger.

ECA Details

Preconditions

- C1 is CASE_OWNER; case attributed_to=C1.

Steps

1. [c1] POST invite-actor-to-case trigger targeting C2 (CVDRole.COORDINATOR) → C1 sends Invite activity to CaseActor; CaseActor forwards to C2
2. [c2] POST accept-case-invite trigger → C2 joins the case (active) with CVDRole.COORDINATOR

Postconditions

- C2 is a participant; CVDRole.COORDINATOR; case attributed_to=C1.

Extends: DEMOMA-14-002
DEMOMA-14-019 MUST In the RCCV-handoff scenario, C2 MUST accept C1's invitation.

C2 is a participant only once it accepts. Until then, C1 has no participant to offer the ownership transfer to.
Depends on: DEMOMA-14-003
DEMOMA-14-004 MUST C1 MUST offer case ownership transfer to C2 (TRIG-11-001).

The ownership transfer is the step that makes this scenario different from RCCV-extension. The trigger pair (TRIG-11-001, TRIG-11-002) is the same mechanism that RVCV-handoff uses (DEMOMA-11-002). Thus the transfer is tested from a Vendor and from a Coordinator, and a defect that occurs for only one of these roles is found.

ECA Details

Preconditions

- C2 is a participant; case attributed_to=C1.

Steps

1. [c1] POST offer-case-ownership-transfer trigger targeting C2 → C1 sends Offer activity to C2's inbox via CaseActor
2. [c2] POST accept-case-ownership-transfer trigger referencing the Offer → case attributed_to=C2 on C1's and C2's DataLayers; C2 holds CVDRole.CASE_OWNER; C1 holds CVDRole.COORDINATOR

Postconditions

- case attributed_to=C2 on C1's and C2's DataLayers.
- C2 holds CVDRole.CASE_OWNER; C1 holds CVDRole.COORDINATOR.

Extends: DEMOMA-14-003
Depends on: TRIG-11-001
DEMOMA-14-020 MUST C2 MUST accept C1's offer of case ownership transfer (TRIG-11-002).

The transfer completes only when the new owner accepts it. C2's accept trigger is the step after which C2 holds CASE_OWNER and C1 holds COORDINATOR.
Depends on: DEMOMA-14-004
Depends on: TRIG-11-002
DEMOMA-14-005 MUST C2, the new CASE_OWNER, and not C1, MUST invite the Vendor to the case.

This invariant confirms that the new CASE_OWNER (C2) has the authority to extend the case to additional actors after the handoff.

ECA Details

Preconditions

- case attributed_to=C2; C2 is CASE_OWNER.

Steps

1. [c2] POST invite-actor-to-case trigger for Vendor → C2 sends Invite activity to CaseActor; CaseActor forwards to Vendor
2. [vendor] POST accept-case-invite trigger directed to CaseActor → Vendor joins the case (active); Accept delivered to CaseActor inbox

Postconditions

- Vendor is a participant; all five actors have case replicas.

Extends: DEMOMA-14-004
DEMOMA-14-021 MUST In the RCCV-handoff scenario, the Vendor MUST accept C2's invitation.

The Vendor's acceptance shows that the four-actor coordination path works end to end after the handoff.
Depends on: DEMOMA-14-005
DEMOMA-14-006 MUST After the Vendor joins, all four actor containers (Reporter, C1, C2, Vendor) MUST converge to the same case ledger state (LedgerFanout invariant).

Verifying convergence here ensures the ownership-transfer workflow does not break LedgerFanout convergence.
DEMOMA-14-022 MUST In the RCCV-handoff scenario, the Vendor MUST receive the complete ledger backfill from genesis.

Late-joiner backfill is a shared invariant across RVCV-extension, RVCV-handoff, and RCCV-handoff. The Vendor joins after the ownership transfer, so its replica must hold every entry from before it joined.
Extends: DEMOMA-14-006
DEMOMA-14-007 MUST Vendor MUST advance to CS.VFd (fix ready) and stop there.

The RCCV-handoff Vendor is invited with the VENDOR role alone, and CSB-15-002 refuses a fix-deployed (d → D) report from a participant without the DEPLOYER role. Reaching VFd exercises the Vendor's whole fix-readiness path; deployment is shown by the scenarios that invite a Vendor as VENDOR and DEPLOYER.
Depends on: CSB-15-002
DEMOMA-14-008 MUST The RCCV-handoff scenario MUST get its vultron-demo rccv-handoff sub-command from its @scenario registration, not from a command declared in vultron/demo/cli/ (DEMOCI-11-011).

The Docker entrypoint forwards the DEMO=rccv-handoff value to vultron-demo rccv-handoff (demo-entrypoint.sh). The CLI generates that sub-command from the scenario registry, so a hand-declared command would be a second copy that can drift from the registry (ADR-0098).
Refines: DEMOCI-11-011
DEMOMA-14-023 MUST The vultron-demo rccv-handoff sub-command MUST expose the --reporter-url, --c1-url, --c2-url, --vendor-url, --case-actor-url, --reporter-id, --c1-id, --c2-id, --vendor-id and --skip-health-check options.

Each container of the scenario needs an address an operator can override, each cast actor needs an id an operator can override, and a CI run can skip the health check. The CaseActor takes no id option: its container seeds the one fixed CaseActor id of the cast (DEMOCI-11-020), so an override would have nothing to select. The options come from the module's ROLES, so a role that is missing there has no option.
Extends: DEMOMA-14-008
DEMOMA-14-024 MUST Each --*-url and --*-id option of the vultron-demo rccv-handoff sub-command MUST bind to an environment variable.

The Docker entrypoint passes each container's address and actor id through the environment. The CLI generates the binding from each role's url_env and id_env. The --skip-health-check flag has no environment binding.
Extends: DEMOMA-14-008
DEMOMA-14-009 MUST The RCCV-handoff implementation MUST ship a dedicated per-scenario case-ledger invariant test file (test/ci/invariants/test_rccv_handoff_invariants.py) built exclusively on the shared invariant library (per DEMOMA-12-008 pattern).

Scenario-specific invariants prevent the RCCV-handoff scenario from accidentally omitting protocol steps not covered by universal checks. The Vendor-as-late-joiner invariant is shared with RVCV-extension (DEMOMA-10) and RCCV-extension (DEMOMA-13).
See also: DEMOMA-12-008 — a sibling scenario's pattern ("per ... pattern")
DEMOMA-14-010 MUST C2 MUST be a participant with CVDRole.COORDINATOR before the ownership transfer is initiated in the RCCV-handoff scenario.

C2 must be a known case participant before C1 can offer ownership transfer; the invite-accept flow in DEMOMA-14-003 and DEMOMA-14-019 establishes C2's presence in the ledger.
DEMOMA-14-011 MUST After the RCCV-handoff ownership transfer, the case's attributed_to MUST reflect C2 on C1's DataLayer, C2's DataLayer, and the CaseActor's canonical ledger.

attributed_to reflects the current CASE_OWNER; all replicas must converge on the updated value after the ownership transfer completes.
DEMOMA-14-012 MUST After the RCCV-handoff ownership transfer, C1's CVDRole MUST become CVDRole.COORDINATOR (no longer CASE_OWNER).

This is the defining role-change outcome of the handoff; C1 retains participation but surrenders ownership authority.
DEMOMA-14-013 MUST The Vendor's Accept activity MUST be delivered to the CaseActor so AcceptInviteActorToCaseBT runs and the join is committed to the canonical ledger (PCR-08-008).

Accept must reach the CaseActor, not just the inviting actor, so the join is recorded in the authoritative ledger.
Refines: PCR-08-008
DEMOMA-14-014 MUST All participants MUST report publication (CS.VFDPx or CS.VFDPxa) in the RCCV-handoff scenario.

Public disclosure is the CS.P step that the end of the scenario rests on. Each participant's report shows that the publication reached it.
DEMOMA-14-025 MUST The embargo MUST terminate (EM.EXITED) in the RCCV-handoff scenario.

Public disclosure triggers embargo teardown via ThreatTerminationBranchNode; both outcomes must be confirmed to validate the end-to-end CS.P path.
Depends on: DEMOMA-14-014
DEMOMA-14-015 MUST All participants MUST close the case (RM.CLOSED) in the RCCV-handoff scenario.

RM.CLOSED for all participants is the terminal acceptance criterion for the full CVD lifecycle in the RCCV-handoff scenario.
DEMOMA-14-016 MUST The RCCV-handoff invariant test file MUST assert the following scenario-specific checks in addition to universal library checks: (1) validate_report event present in case-actor log, (2) invite_actor_to_case present at least twice (C2 invitation + Vendor invitation), (3) accept_invite_actor_to_case present at least twice (C2 accept + Vendor accept), (4) close_case present, (5) CS transitions VFd and VFD observed in add_participant_status_to_participant entries for the Vendor actor, and (6) Vendor replica holds the complete log from genesis (late-joiner full-history backfill).

Scenario-specific invariants prevent the RCCV-handoff scenario from accidentally omitting protocol steps not covered by universal checks.
DEMOMA-14-017 MUST The RCCV-handoff story MUST start with the same shared opening as RCCV-extension (DEMOMA-13-012) and continue from C1's decision to offer ownership.

The two scenarios part at one decision, so everything before it is one copy of the code and their recordings are byte-identical up to the owner-keep-case branch point (DEMOCI-11-018). It also makes C2 an active participant holding the coordinating role before the transfer is offered, which DEMOMA-14-010 requires. Naming it here keeps this group a whole story.
Refines: DEMOMA-17-001
Uses definition from: DEMOMA-13-012

Demo Helper Preconditions

ID Priority Requirement Related
DEMOMA-15-001 MUST verify_fix_ready in vultron/demo/helpers/milestones/lifecycle.py MUST accept only actor IDs holding CVDRole.VENDOR in the case's participant index; the f→F (fix-ready) transition is gated on VENDOR by CheckVendorRoleNode.

The f→F (fix-ready) transition requires CVDRole.VENDOR, and a Coordinator has no vendor fix path. If verify_fix_ready accepted any actor, a call with a Coordinator would fail only later, as a fix-ready state that never appears. That failure does not show its cause. The role check names the wrong actor at once. An actor that holds both VENDOR and DEPLOYER passes the check.
DEMOMA-15-002 MUST verify_fix_deployed MUST accept only actor IDs holding CVDRole.DEPLOYER in the case's participant index; the d→D (fix-deployed) transition is gated on DEPLOYER by CheckDeployerRoleNode.

A VENDOR-only actor stops at VFd and cannot advance to VFD (CSB-15-002); requiring DEPLOYER makes the failure mode unambiguous when the wrong actor ID is passed.
DEMOMA-15-003 MUST Each demo helper (verify_fix_ready and verify_fix_deployed) MUST enforce its role precondition at runtime, raising AssertionError with the actor ID and its actual roles if the assertion fails.

Runtime enforcement surfaces caller errors immediately with a clear diagnostic rather than a confusing downstream VFD state-check failure.
DEMOMA-15-004 MUST verify_stops_at_fix_ready MUST raise AssertionError, naming the actor and its roles, unless that actor holds CVDRole.VENDOR and not CVDRole.DEPLOYER in the case's participant index.

A milestone labelled "stops at VFd" claims a ceiling, not a moment: only a VENDOR without DEPLOYER is barred from d→D (CSB-15-002). Passed a DEPLOYER, the same read says "it has not deployed yet", which a later deployment falsifies while the label still claims the ceiling. The role guard, not a polling wait, is therefore what makes this negative assertion sound, which is why the helper polls for nothing.
Refines: DEMOMA-15-003
Uses definition from: CSB-15-002
DEMOMA-15-005 MUST verify_stops_at_fix_ready MUST assert, on the receiver's replica and on the reporter's, that the participant's latest status records no fix-deployed (D) state.

The claim is the absence of D, not d_state == d: a participant holding no DEPLOYER role carries no d dimension at all, so its D state reads as absent and pinning the expected set to d would fail on the very shape the claim is about. Reading both replicas is what DEMOMA-06-003 asks of every milestone.
Refines: DEMOMA-06-002
Uses definition from: CSB-15-002
DEMOMA-15-006 MUST A milestone helper asserting the absence of a state transition MUST NOT be preceded by a polling wait for that state.

DEMOMA-06-006 obliges a poll before each milestone helper that asserts a state was reached, because a replica catches up asynchronously. An absence has nothing to wait for: a poll could only time out, and a timeout rewritten as a longer wait would hide the claim rather than check it. What makes the negative assertion sound is the role guard the transition's own gate rests on (DEMOMA-15-004, CSB-15-002), so the helper reads once and the guard, not a timeout, carries the claim.
Refines: DEMOMA-06-006
Uses definition from: DEMOMA-15-004

Per-Scenario Required Semantic Types for the Invariant Harness

Each scenario defines a minimum set of protocol semantic types that MUST appear in the authoritative (case-actor) case-ledger log for a complete, correct run. These lists are implemented as the per-scenario _XXX_EXPECTED_SEMANTIC_TYPES constants in the corresponding test/ci/invariants/test_XXX_invariants.py file and are checked by Invariant 5 (test_invariant_5_expected_semantic_types_present). They complement, and do not replace, the scenario-specific invariant test functions that use check_semantic_type_count for events that must appear multiple times.

ID Priority Requirement Related
DEMOMA-16-001 MUST The five universal semantic types — validate_report, add_participant_status_to_participant, close_case, add_note_to_case, and engage_case — MUST appear at least once in the authoritative case-actor log for every multi-actor demo scenario.

These five types are the minimum for every scenario: report validation, RM engagement (VALID to ACCEPTED), participant status, case closure, and at least one note (the add-note trigger posts one inline Add(Note)). A scenario without one of the five has not completed the basic CVD lifecycle. The shared demo helpers emit engage_case, so no scenario file calls the trigger, but every scenario produces the entry. Paths: see notes/demo-ci-invariants.md.
Refines: DEMOMA-03-002
DEMOMA-16-002 MUST In addition to the universal types (DEMOMA-16-001), the rv scenario MUST verify that its expected-semantic-types list is restricted to types that the rv scenario actually produces. rv does not include an invite_actor_to_case phase; the Reporter joins by submitting a report, not via an invitation.

An expected type that rv never produces makes the check fail on every correct run, and a developer then learns to ignore it. rv has no invitation phase, because the Reporter joins when it submits the report. The list must contain only the types that a correct rv run produces, so that a missing type always means a defect.
Uses definition from: DEMOMA-16-001
DEMOMA-16-003 MUST The RVV scenario expected-semantic-types list MUST include invite_actor_to_case and accept_invite_actor_to_case in addition to the universal types (DEMOMA-16-001), because Vendor1 invites Vendor2 into the case and Vendor2 explicitly accepts via the accept-case-invite trigger.

Without these two types in the list, a run in which Vendor2 never joined can still pass the type check. The invitation and its acceptance are the steps that make Vendor2 a participant, so their ledger entries are the evidence that RVV ran as specified.
Extends: DEMOMA-16-001
Derives from: DEMOMA-09-002
DEMOMA-16-004 MUST The RVCV-extension scenario expected-semantic-types list MUST include invite_actor_to_case, offer_case_participant, accept_invite_actor_to_case, and accept_actor_recommendation in addition to the universal types (DEMOMA-16-001), because Vendor1 invites Coordinator, Coordinator uses the ADR-0026 suggest-actor flow (offer_case_participant) to propose Vendor2, Vendor1 approves the recommendation (accept_actor_recommendation), CaseActor converts the approval into an invitation, and Vendor2 explicitly accepts via the accept-case-invite trigger.

Each listed type is the ledger evidence of one step in the suggest and approve flow. If one is missing from the list, a run in which that step never happened can still pass. The invitation types occur once for each invitee, so their presence shows only that one invitee joined. The count checks in the harness show that both the Coordinator and Vendor2 joined.
Extends: DEMOMA-16-001
DEMOMA-16-005 MUST The RVCV-handoff scenario expected-semantic-types list MUST include invite_actor_to_case, accept_invite_actor_to_case and accept_case_ownership_transfer in addition to the universal types (DEMOMA-16-001), because Vendor1 invites Coordinator, the Coordinator accepts the invitation and then accepts the ownership transfer to become the new CASE_OWNER (TRIG-11-002, CM-21-007), and Coordinator then invites Vendor2 who also accepts.

The ownership transfer is the step that makes this scenario different from RVCV-extension. Without accept_case_ownership_transfer in the list, a run in which the Coordinator never became the Case Owner can still pass the type check. The invitation types show that the invitation step ran. The count checks in the harness show that both the Coordinator and Vendor2 joined.
Extends: DEMOMA-16-001
See also: CM-21-007 — a cited rationale
See also: TRIG-11-002 — a cited rationale
DEMOMA-16-006 MUST The RCCV-handoff scenario expected-semantic-types list MUST include invite_actor_to_case, accept_invite_actor_to_case and accept_case_ownership_transfer in addition to the universal types (DEMOMA-16-001), because C1 invites C2, C2 accepts the invitation and then accepts the ownership transfer to become the new CASE_OWNER (TRIG-11-002, CM-21-007), and C2 then invites the Vendor who also accepts.

The ownership transfer is the step that makes this scenario different from RCCV-extension. Without accept_case_ownership_transfer in the list, a run in which C2 never became the Case Owner can still pass the type check. The invitation types show that the invitation step ran. The count checks in the harness show that both C2 and the Vendor joined.
Extends: DEMOMA-16-001
Extends: DEMOMA-14-009
See also: CM-21-007 — a cited rationale
See also: TRIG-11-002 — a cited rationale
DEMOMA-16-007 MUST The RCV scenario expected-semantic-types list MUST include invite_actor_to_case and accept_invite_actor_to_case in addition to the universal types (DEMOMA-16-001), because the Coordinator invites the Vendor into the case and the Vendor explicitly accepts via the accept-case-invite trigger. The Reporter is seated at case creation and is not invited (DEMOMA-12-003).

Without these two types, a run in which the Vendor never joined can still pass the type check. The Reporter is seated at case creation, so the invitation types in RCV are evidence about the Vendor only.
Extends: DEMOMA-16-001
Extends: DEMOMA-12-008
See also: DEMOMA-12-003 — context for the reader
DEMOMA-16-008 MUST The per-scenario expected-semantic-types list in each test/ci/invariants/test_XXX_invariants.py file MUST match its DEMOMA-16 requirement.

The test list is the code form of the requirement. If the two drift, the test can check for a type that the scenario does not produce, or it can stop checking for a step that the scenario still needs. A step can then be lost without a failure.
Refines: DEMOCI-04-004
DEMOMA-16-018 MUST A PR that adds or removes a scenario phase MUST update both the DEMOMA-16 requirement and the test list.

One change that updates both keeps them the same. A list updated in a later PR leaves a window in which the test and the requirement disagree.
Implements: DEMOMA-16-008
DEMOMA-16-009 MUST The RCVCV scenario expected-semantic-types list MUST include invite_actor_to_case, offer_case_participant, accept_invite_actor_to_case, and accept_actor_recommendation in addition to the universal types (DEMOMA-16-001).

RCVCV has two coordinators and two vendors. C1 invites V1 and C2 directly. C2 suggests V2 through the suggest and approve flow (ADR-0026): C1 approves the recommendation, the CaseActor invites V2, and V2 accepts. Each listed type is the ledger evidence of one of these steps. A type that is missing shows a step that never happened. The count checks in the harness show that all three invitees joined.
Extends: DEMOMA-16-001
DEMOMA-16-010 MUST The RCCV-extension scenario expected-semantic-types list MUST include invite_actor_to_case, offer_case_participant, accept_invite_actor_to_case, and accept_actor_recommendation in addition to the universal types (DEMOMA-16-001), because Coordinator1 invites Coordinator2, Coordinator2 uses the ADR-0026 suggest-actor flow (offer_case_participant) to propose the Vendor, Coordinator1 approves the recommendation (accept_actor_recommendation), CaseActor converts the approval into an invitation, and the Vendor explicitly accepts via the accept-case-invite trigger.

Each listed type is the ledger evidence of one step in the suggest and approve flow. If one is missing from the list, a run in which that step never happened can still pass. C2 and the Vendor each accept an invitation, so the presence of accept_invite_actor_to_case shows only that one of them joined. The count checks in the harness show that both joined.
Extends: DEMOMA-16-001
DEMOMA-16-011 MUST The RCV-reject scenario expected-semantic-types list MUST include invite_actor_to_case and reject_invite_actor_to_case in addition to the universal types (DEMOMA-16-001), because the Coordinator invites the Vendor and the Vendor sends Reject(Invite(VulnerabilityCase preview)[target=Actor]) (an invitation-layer rejection), which triggers RejectInviteActorToCaseReceivedUseCase on the CaseActor and produces the reject_invite_actor_to_case ledger entry. The Vendor never sends Accept(Invite(VulnerabilityCase preview)[target=Actor]), so accept_invite_actor_to_case does NOT appear in this scenario.

The rejection is the step that this scenario exists to show, so its ledger entry must be in the list. The list must not contain accept_invite_actor_to_case, because a correct run never produces it. If it were in the list, every correct run would fail.
Extends: DEMOMA-16-001
Derives from: DEMOMA-27-006
DEMOMA-16-012 MUST In the RCVCV scenario, the case-actor log MUST record invite_actor_to_case at least three times (C1 invites V1, C1 invites C2, and CaseActor invites V2 via the ADR-0026 path) and offer_case_participant at least once (C2 suggests V2 to C1 via the ADR-0026 suggest-actor flow).

These counts confirm that the multi-party invitation and suggest-actor flows were exercised end-to-end, not just that the semantic types appear at least once.
DEMOMA-16-013 MUST In the RCVCV scenario, the case-actor log MUST record accept_actor_recommendation at least once (C1 approves C2's recommendation) and accept_invite_actor_to_case at least three times (V1, C2, and V2 each accept their respective invitations).

These counts verify that every actor who received an invitation explicitly accepted, and that the ADR-0026 approval path was exercised.
DEMOMA-16-015 MUST The VC scenario expected-semantic-types list MUST include invite_actor_to_case and accept_invite_actor_to_case in addition to the universal types (DEMOMA-16-001), because Vendor invites Coordinator into the case as CVDRole.OBSERVER and Coordinator explicitly accepts via the accept-case-invite trigger.

Vendor is CASE_OWNER from self-reporting, so Vendor drives the direct invite-actor-to-case trigger (no suggest/approve chain). Coordinator accepts and becomes a signatory by accepting the embargo. No offer_case_participant or accept_actor_recommendation events are expected because there is no second-level recommendation in this two-actor scenario.
Extends: DEMOMA-16-001
DEMOMA-16-016 MUST The RCV-embargo scenario expected-semantic-types list MUST include invite_actor_to_case, accept_invite_actor_to_case, invite_to_embargo_on_case, accept_invite_to_embargo_on_case, activate_embargo_on_case and remove_embargo_event_from_case in addition to the universal types (DEMOMA-16-001), because the Coordinator invites the Vendor and the Vendor accepts, the Reporter's embargo proposal and its relayed invitations are committed, the Vendor accepts it, the owner activates it (VAM-05-008), and the Coordinator terminates the embargo.

The embargo semantic types are the ones the CASE_MANAGER's commit path emits (DEMOMA-20-016); the harness imports them from that code, so a rename there fails the harness rather than leaving it checking a stale string.
Extends: DEMOMA-16-001
See also: VAM-05-008 — a cited rationale
DEMOMA-16-017 MUST The RCVV-embargo scenario expected-semantic-types list MUST include invite_actor_to_case, accept_invite_actor_to_case, invite_to_embargo_on_case, accept_invite_to_embargo_on_case, activate_embargo_on_case and remove_embargo_event_from_case in addition to the universal types (DEMOMA-16-001), because the Coordinator invites both Vendors and they accept, the Reporter's and Vendor1's embargo proposals and their relayed invitations are committed, the other participants accept them, the owner activates each revision (VAM-05-008), and the embargo is torn down when the Reporter reports publication.

The embargo semantic types are the ones the CASE_MANAGER's commit path emits (DEMOMA-21-022); the harness imports them from that code, so a rename there fails the harness rather than leaving it checking a stale string.
Extends: DEMOMA-16-001
See also: VAM-05-008 — a cited rationale
DEMOMA-16-019 MUST The RV-CSAF scenario expected-semantic-types list MUST include invite_to_embargo_on_case, accept_invite_to_embargo_on_case and remove_embargo_event_from_case, besides the universal types (DEMOMA-16-001). They record the relayed revision of the Vendor's longer default, its acceptance, and the end of the embargo.

The relayed revision is what shortest-wins leaves behind when the CSAF date is the shorter term (EP-04-003, EP-04-027); without its entries a run in which the Vendor's default never competed passes the type check.
Extends: DEMOMA-16-001
DEMOMA-16-014 MUST The RCVD scenario expected-semantic-types list MUST include invite_actor_to_case and accept_invite_actor_to_case in addition to the universal types (DEMOMA-16-001), because the Coordinator invites Reporter, Vendor, and Deployer into the case, and all three explicitly accept via the accept-case-invite trigger.

RCVD exercises a four-actor coordination chain with one full invitation cycle per actor other than the Case Owner; invite_actor_to_case and accept_invite_actor_to_case confirm the invitation/accept path was exercised for each. Unlike scenarios with ADR-0026 suggest-actor flows, RCVD uses only direct invitations from the Case Owner.
Extends: DEMOMA-16-001

In-Process Fuzz Simulation Scenario

ID Priority Requirement Related
DEMOMA-18-001 MUST The fuzz simulation scenario MUST run entirely in-process, with no HTTP servers, containers or network I/O.

The scenario explores the protocol state space by chance, so it must run quickly and many times. Containers and network setup would make it too slow for local development and CI smoke tests.
Supersedes: DEMOMA-01-001
DEMOMA-18-009 MUST In the fuzz simulation scenario, each actor MUST have its own isolated in-memory DataLayer.

Separate in-memory DataLayers keep each actor separate, as in the container demos (DEMOMA-01-001). An actor that shares a store with another could read the other's state directly, so the simulation would not test the messages between them.
Extends: DEMOMA-18-001
DEMOMA-18-002 MUST The fuzz simulation scenario MUST support a configurable number of iterations N, with a default of 10.

One iteration is one sample of the protocol state space. A configurable count lets a user take a few samples for a quick check or many for a wider search.
DEMOMA-18-010 MUST Each iteration of the fuzz simulation scenario MUST start with fresh in-memory DataLayers for all actors and carry no state from an earlier iteration.

Each iteration is an independent probabilistic sample of the protocol state space. Shared state would cause later iterations to depend on earlier ones, undermining the exploration goal.
Extends: DEMOMA-18-002
DEMOMA-18-003 MUST The fuzz simulation scenario MUST use STOCHASTIC call-out point bundles for all actors so that each call-out decision is drawn from the fuzzer node probability distribution rather than a deterministic default.

The scenario's purpose is probabilistic state-space exploration. DETERMINISTIC bundles would produce an identical path on every iteration, defeating the simulation goal.
DEMOMA-18-004 MUST The fuzz simulation scenario MUST simulate in-process message delivery between actors by directly invoking the receiving actor's dispatcher with the emitted activity; no HTTP, ASGIEmitter, or real network transport is permitted.

A direct call to the dispatcher of the receiving actor delivers each emitted activity without network setup. The receiver still runs its own received use case and behavior tree, so the simulation tests the protocol logic of both actors and not only that of the sender.
Implements: DEMOMA-18-001
DEMOMA-18-005 MUST Each iteration MUST log structured output at INFO level including: the iteration number, each call-out point node name and its SUCCESS/FAILURE outcome, and the final RM/EM/CS state per actor.

Per-run logging is the primary diagnostic output of the scenario; it allows users to observe which protocol paths were exercised across iterations.
DEMOMA-18-006 MUST The fuzz simulation scenario MUST be accessible via the vultron demo fuzz CLI sub-command, which accepts at least an --iterations N option.

Consistent with the existing vultron demo CLI structure (DC-01-001 through DC-01-005); the fuzz sub-command makes the scenario discoverable alongside other demo commands.
DEMOMA-18-011 MUST The CLI help text of vultron demo fuzz MUST document the default number of iterations.

A user who runs the sub-command without --iterations gets the default count. The help text is where the user learns how many iterations that run will take.
Extends: DEMOMA-18-006
DEMOMA-18-007 MUST NOT The fuzz simulation scenario MUST NOT modify an existing deterministic demo scenario.

The deterministic scenarios give the same result on each run. A change made for the fuzz scenario would put that repeatability at risk.
DEMOMA-18-012 MUST NOT The fuzz simulation scenario MUST NOT import from or depend on any module under vultron/demo/scenario/.

The fuzz scenario is a standalone simulation tool; coupling it to deterministic scenario files would break their repeatability and make the fuzz scenario harder to isolate.
Extends: DEMOMA-18-007
DEMOMA-18-008 MUST A unit test in test/demo/ MUST verify that the fuzz simulation scenario completes a single iteration without raising an exception.

The test provides a regression guard confirming the scenario still runs after code changes, independent of the specific protocol path taken.
DEMOMA-18-013 MUST The fuzz simulation unit test of DEMOMA-18-008 MUST run with a seeded RNG where possible.

The scenario draws each call-out decision at random. A seeded RNG makes a failing run repeat, so a developer can reproduce the failure and debug it.
Extends: DEMOMA-18-008

Demo Code Reuse and DRY

ID Priority Requirement Related
DEMOMA-17-001 MUST Before a scenario file under vultron/demo/scenario/ uses a pattern for the second time, its author MUST extract the pattern to vultron/demo/helpers/.

A shared helper gives each pattern one place, so one fix reaches every scenario that uses the pattern. A second inline use is the point at which two copies start to drift.
Refines: CS-22-001 — MUST-level specialisation of the project-wide SHOULD rule for demo scenario files
DEMOMA-17-003 MUST NOT A scenario file MUST NOT copy-paste a function body, polling loop, verification block or any other logical unit from an existing scenario file.

A scenario written by copying an earlier scenario copies its defects together with its correct patterns. A fix then lands in one copy and not in the others.
Extends: DEMOMA-17-001
DEMOMA-17-002 MUST NOT A consolidation change extracts or merges demo helpers, phases or scenario bodies under DEMOMA-17-001. Such a change MUST NOT change what any demo scenario passes or fails on.

A consolidation should change only where the code is, not what it checks. If it also makes a check weaker or stronger, the change in the verdict is hidden inside a refactor, where reviewers do not look for it. A recording alone is not the evidence: a check can move or change its subject and leave it unchanged. The evidence is DEMOCI-11-055's base-versus-head comparison.
Constrains: DEMOMA-17-001
DEMOMA-17-004 MUST An author MUST change a demo scenario's verdict in its own change, with its own issue, and not in a consolidation change.

A change with its own issue makes the verdict change visible, and reviewers can judge it on its own. Inside a consolidation, the same change hides among moves that should change nothing.
Extends: DEMOMA-17-002

RCVCV 5-Party Scenario (Reporter + Coordinator1 + Vendor1 + Coordinator2 + Vendor2)

Specifies the RCVCV multi-actor demo scenario: a 5-party CVD case with Reporter (F), Coordinator1 (C1), Vendor1 (V1), Coordinator2 (C2), and Vendor2 (V2). C1 receives the report and creates the case. C1 invites V1 and C2. C2 suggests V2 to C1 via the ADR-0026 suggest-actor flow; C1 approves; CaseActor invites V2. V1 holds only CVDRole.VENDOR (reaches VFd, fix-ready, but has no deploy path). V2 holds both CVDRole.VENDOR and CVDRole.DEPLOYER (full VFD path). V1 triggers CS.P first, causing CaseActor to initiate embargo teardown via ThreatTerminationBranchNode. This scenario is the first to exercise: (a) two independent coordinators, (b) two vendor actors with different role sets, (c) embargo teardown triggered by a non-CASE_OWNER vendor participant's publication.

Trigger: Scenario Start — rcvcv

ID Priority Requirement Related
DEMOMA-19-001 MUST The RCVCV scenario MUST seat V2 (VendorDeployer) in a character-actor slot of the fixed cast (DEMOCI-11-020).

The RCVCV scenario needs five independent actor containers — one per scenario actor — to force all inter-actor communication over the network wire protocol (DEMOMA-01-001). Keeping one actor per container preserves the architectural isolation invariant that prevents intra-container data-layer shortcuts (ADR-0042). V2 holds VENDOR and DEPLOYER from the Invite that seats it, so its container declares no default case roles (DEMOCI-11-021).
Refines: DEMOCI-11-020
DEMOMA-19-023 MUST Each cast slot RCVCV seats MUST have a service built from the shared *actor-service anchor, with its own volume, port variable and actor id.

One anchor for every actor service keeps the image build and the health check identical across the cast, so a per-container stanza holds only what actually differs. Its seed config is DEMOCI-11-028. One actor per container preserves the isolation invariant that prevents intra-container data-layer shortcuts (ADR-0042).
Extends: DEMOMA-19-001
DEMOMA-19-002 MUST A seed_containers_rcvcv function MUST be added to vultron/demo/helpers/seeding/ accepting five DataLayerClient arguments (reporter_client, c1_client, v1_client, c2_client, v2_client) and five optional deterministic actor ID arguments.

The 5-actor cross-registration ensures that every actor can locate and deliver activities to every other actor without runtime DNS surprises. The N×(N-1) pattern is established by all existing multi-actor seed functions (seed_containers_rvv, seed_containers_rvcv, seed_containers_rccv).
Extends: DEMOMA-19-001
DEMOMA-19-003 MUST The RCVCV scenario MUST be implemented at its derived demo path (DEMOCI-11-003): the vultron/demo/scenario/rcvcv_demo/ package, or a module of the same name in the same directory.

The scenario registry derives the script path, the test harness path and the narrative path from the scenario name (ADR-0098, DEMOCI-11-003). A script at any other path is not found by these tools. The fixed path keeps the registered rcvcv scenario and its files together. Either form keeps that path, so the scenario can become a package when it outgrows one module (CS-18-001).
Uses definition from: DEMOCI-11-003
DEMOMA-19-004 MUST The RCVCV scenario MUST assign V1 only CVDRole.VENDOR, with no DEPLOYER role.

V1's vendor-only role set (stops at VFd) and V2's vendor-deployer role set (reaches VFD) are the key differentiators of this scenario. The distinction verifies DEMOMA-15-001's precondition guards: verify_fix_ready requires VENDOR; verify_fix_deployed requires DEPLOYER. Using V1 in a verify_fix_deployed call would exercise the wrong path and mask a future regression where the d→D BT gate is weakened.
DEMOMA-19-026 MUST The RCVCV scenario MUST assign V2 both CVDRole.VENDOR and CVDRole.DEPLOYER.

V2 is the one vendor in the scenario that can reach VFD. With the DEPLOYER role it has a deploy path, so verify_fix_deployed runs for it while V1 stops at VFd.
Extends: DEMOMA-19-004
DEMOMA-19-005 MUST In the RCVCV scenario, V1 MUST publish before V2.

V1 publishes first so that the scenario tests a teardown that a VENDOR participant who is not the Case Owner starts. ThreatTerminationBranchNode does not gate teardown on the role of the sender (RSH-03-002).
DEMOMA-19-027 MUST Before V2 publishes, the RCVCV scenario MUST wait until the CaseActor has processed V1's CS.P participant status update and emitted the embargo teardown (EM.EXITED).

If V2 publishes before the teardown commits, the two publications race, and the ledger order changes from run to run. The wait makes the teardown a result of V1's publication alone.
Extends: DEMOMA-19-005
DEMOMA-19-006 MUST The RCVCV scenario MUST be registered in the scenario registry under the name rcvcv. The CLI generates the rcvcv sub-command from the registry (DEMOCI-11-011), consistent with the naming convention of existing scenario commands (rv, rvv, rcv, rvcv, rccv).

The CLI is the single entry point for all demo scenarios (DC-01-001), and it builds one sub-command for each registered scenario (DEMOCI-11-011). A scenario that is not registered is not reachable from vultron demo rcvcv, and it has no entry in the CI matrix.
See also: DEMOCI-11-011 — descriptive: names the registration the scenario then has
DEMOMA-19-007 MUST The RCVCV scenario MUST be registered with the scenario registry (DEMOCI-11-001), so that its generated .github/demo-scenarios.json entry (DEMOCI-11-004) adds it to the CI matrix.

CI coverage of all demo scenarios is required by DEMOCI-04-001. RCVCV is the widest scenario, so it is the one that sets the size of the cast. DEMOMA-19-023 is what places each of those containers in the compose file CI starts as a whole; this requirement no longer carries that half. Scenario-role names in devlogs match the names used in scenario code, making log archaeology easier.
Refines: DEMOCI-11-001
See also: DEMOCI-11-004 — descriptive: names the registration the scenario then has
DEMOMA-19-008 MUST An invariant harness file MUST be created at test/ci/invariants/test_rcvcv_invariants.py with _DEMO_NAME = "rcvcv", a _CHAIN_ACTORS list of scenario-role actor names (reporter, c1, v1, c2, v2, case-actor), and _RCVCV_EXPECTED_SEMANTIC_TYPES per DEMOMA-16-009.

The invariant harness is the CI acceptance test for the scenario. The scenario-specific checks show that each of the three invitees was invited and accepted, and that C2 made its suggestion. The chain checks for each actor show that each of the six devlogs holds a ledger with no gaps.
Uses definition from: DEMOMA-16-009
DEMOMA-19-009 MUST The RCVCV scenario MUST exercise the ADR-0026 suggest-actor flow for V2's onboarding: C2 posts suggest-actor-to-case, CaseActor forwards an Offer(CaseParticipant) to C1, C1 posts accept-actor-recommendation, CaseActor sends Invite to V2, and V2 posts accept-case-invite.

This flow adds a new participant through a suggestion from a coordinator that is not the Case Owner (ADR-0026). It is the path that admits V2. The invitation must arrive through normal delivery and be found by polling. A demo that posts the invitation into the inbox of V2 would skip the delivery path that the scenario exists to test (DEMOMA-00-002).
DEMOMA-19-010 MUST Every cast container the RCVCV scenario seats MUST have its own seed config in docker/seed-configs/.

RCVCV is the widest scenario, so it is the first to need a seed config for every cast container. The cast-wide shape of those configs is DEMOCI-11-028 (the local actor), DEMOCI-11-029 (the peer mesh) and DEMOCI-11-033 (the display name), which together replace the id, name and peer list this requirement used to spell for one container.
Refines: DEMOCI-11-028
DEMOMA-19-011 MUST The demo-runner service MUST wait for every cast container the RCVCV scenario seats.

RCVCV seats every cast container, so its run is the one that waits for all of them. The cast-wide form of the wait and of the matching environment variables is DEMOCI-11-030 and DEMOCI-11-031.
Refines: DEMOCI-11-030
DEMOMA-19-012 MUST The seed_containers_rcvcv function MUST create five local actors: Reporter (Person), Coordinator1 (Organization), V1 named Vendor (Organization), Coordinator2 (Organization), and VendorDeployer (Organization).

Each of the five scenario participants requires a typed local actor record in its container's DataLayer before cross-registration. V1 is named Vendor, as the one Vendor of rcv is, because rcvcv shares rcv's path up to C1's decision and their ledgers must match there, the name included (DEMOCI-11-017).
DEMOMA-19-013 MUST The seed_containers_rcvcv function MUST register every actor as a known peer on each of the other four containers (N×(N-1) = 20 cross-registrations total), following the same Phase 1 / Phase 2 pattern as seed_containers_rccv.

Full cross-registration ensures every actor can locate and deliver activities to every other actor without runtime DNS surprises.
DEMOMA-19-014 MUST The RCVCV scenario MUST tell the following steps in order: report_submission, c2_suggests_v2, sync_verification, notes_exchange, fix_lifecycle, publication, case_closure, and dump_case_ledgers.

Each step depends on the state that the steps before it create. Invitations come before suggestions, the fix lifecycle comes before publication, and publication comes before closure. The ledger dump comes last so that it holds the complete run. The fixed order makes a failure point to one step. The scenario is written as composition (DEMOMA-19-024), so the steps are the fragments of its story rather than phase functions of its own; the order is the order they appear in it.

ECA Details

Preconditions

- All six containers running (Reporter, C1, V1, C2, V2, CaseActor); all actors seeded and cross-registered.

Steps

1. [reporter] report_submission phase — POST submit-report trigger to C1, which then invites V1; the Reporter asks, C1 answers and V1 adds its status with add-note-to-case; C1 then invites C2 → C1 creates the VulnerabilityCase and holds CVDRole.CASE_OWNER; V1 and C2 accept their invitations, and C2's invitation follows the three notes
2. [c2] c2_suggests_v2 phase — C2 asks its static participant-suggestion adapter who else belongs (BT-24-007), then drives the ADR-0026 suggest-actor flow for the V2 it names (DEMOMA-19-009) → the adapter names V2 as VENDOR and DEPLOYER from the scenario's table; C2 posts suggest-actor-to-case; C1 posts accept-actor-recommendation; CaseActor invites V2; V2 posts accept-case-invite
3. [demo-script] sync_verification phase — poll every replica for the participant set → all five participants are present on every replica
4. [demo-script] joiner notes phase — once joined, C2 and V2 add their notes with add-note-to-case → add_note_to_case is recorded in the case-actor log
5. [demo-script] fix_lifecycle phase — advance V1 to VFd and V2 to VFD, calling the verification helpers named by DEMOMA-19-015 → verify_fix_ready passes for V1 and V2; verify_fix_deployed passes for V2 only, because V1 holds no DEPLOYER role
6. [demo-script] publication phase — V1 publishes, then V2 (DEMOMA-19-005) → CaseActor emits the embargo teardown (EM.EXITED) after V1's CS.P update and before V2 publishes
7. [demo-script] case_closure phase — close the case on every participant → RM.CLOSED for every participant in the CASE_MANAGER's store; each participant's replica ends at the entries recording its own closure (CM-23-004)
8. [demo-script] dump_case_ledgers phase → one case-ledger JSONL artifact per actor under devlogs/rcvcv/

Postconditions

- EM.EXITED after V1 reaches CS.P (DEMOMA-19-005); V1 at VFd and V2 at VFD (DEMOMA-19-015); every participant at RM.CLOSED, which the universal Invariant 7 check (test_invariant_7_log_terminates_all_rm_closed) asserts for every scenario rather than this group. Nothing beyond those is restated here: a postcondition is a projection of the group's normative statements, and asserting a state no statement carries would make this block the only place that requirement exists (MS-16-002).

DEMOMA-19-015 MUST The fix lifecycle phase MUST call verify_fix_ready for both V1 and V2 after each advances to VFd.

V1's vendor-only role set (stops at VFd) and V2's vendor-deployer role set (reaches VFD) are the key differentiators of the RCVCV scenario.
DEMOMA-19-028 MUST The fix lifecycle phase MUST call verify_fix_deployed for V2 only, after V2 advances to VFD.

Only V2 holds the DEPLOYER role, so only V2 can reach VFD. A call for V1 would check a transition that V1 has no path to.
Extends: DEMOMA-19-015
DEMOMA-19-016 MUST NOT Demo code MUST NOT call verify_fix_ready with the ID of a DEPLOYER-only actor.

Calling the wrong helper with the wrong actor masks future regressions where the BT gate is weakened; the precondition guards surface the error immediately.
DEMOMA-19-029 MUST NOT Demo code MUST NOT call verify_fix_deployed with the ID of a VENDOR-only actor that has no DEPLOYER role, such as V1.

A VENDOR-only actor has no deploy path. A verify_fix_deployed call for it would exercise the wrong path and hide a regression where the d→D BT gate is weakened.
Extends: DEMOMA-19-016
DEMOMA-19-017 MUST The verify_publicly_disclosed check MUST be called after both V1 and V2 have published in the RCVCV scenario.

Calling the check before both actors have published may produce a spurious failure if the second publication has not yet propagated.
DEMOMA-19-018 MUST The CI devlogs directory for the RCVCV run MUST use the scenario-role naming convention: reporter, c1, v1, c2, v2, case-actor (not docker service names).

Scenario-role names match the names used in scenario code, making log archaeology easier than using docker service names.
DEMOMA-19-019 MUST The RCVCV invariant harness MUST define the universal invariant tests (Invariants 1–5) plus at minimum these scenario-specific invariant tests: invite_actor_to_case appears at least three times (C1→V1, C1→C2, CaseActor→V2), offer_case_participant appears at least once (C2 suggests V2 via ADR-0026), and accept_invite_actor_to_case appears at least three times (V1, C2, V2 each accept).

The three scenario-specific count checks verify that the multi-party invitation and suggest-actor flows were exercised end-to-end.
DEMOMA-19-020 MUST The RCVCV invariant harness MUST load its replicas via load_devlogs(demo_name=_DEMO_NAME) from test/ci/invariants/common.py, following the same self-contained pattern as every prior scenario harness.

Consistent loading via common.py ensures the harness can be run standalone without importing scenario module state.
DEMOMA-19-021 MUST The RCVCV scenario MUST reach its invariant harness file through the demo/test_file pair in its generated .github/demo-scenarios.json entry (DEMOCI-11-004).

The harness path is derived from the registered scenario name by convention (DEMOCI-11-003) and reaches CI only through the generated matrix.
Uses definition from: DEMOCI-11-004
DEMOMA-19-030 MUST NOT This codebase MUST NOT register an invariant harness through a conftest.py scenario mapping.

The CI runner does not read a conftest.py mapping. A harness registered there looks wired but never runs in CI, so it guards nothing.
Extends: DEMOMA-19-021
DEMOMA-19-022 MUST The RCVCV scenario MUST use polling helpers (not post_to_inbox_and_wait) to deliver the invite to V2's inbox, consistent with DEMOMA-00-002.

DEMOMA-00-002 requires that the demo orchestrator never post directly to another actor's inbox; the invite must arrive via the normal routing path and be detected by polling.
Refines: DEMOMA-00-002
DEMOMA-19-024 MUST The RCVCV story MUST start with the shared "the Reporter asks the Vendor" opening (DEMOMA-12-018) and continue from C1's decision to invite a second Coordinator.

Everything up to C1's decision is told identically to RCV, so it is one copy of the code and the two recordings are byte-identical to the coordinator-after-answer branch point (DEMOCI-11-018). Naming it here keeps this group a whole story.
Refines: DEMOMA-17-001
Uses definition from: DEMOMA-12-018
DEMOMA-19-025 MUST C2's and V2's actors MUST be seeded by the step that brings them into the case, not by the shared opening (DEMOMA-19-024).

The shared opening writes the same records in every scenario that starts with it, which is what makes their recordings byte-identical (DEMOCI-11-018). Each actor and peer record written before the case exists is one more read of the recording clock, so seeding five containers in the opening stamped RCVCV's first ledger entry a third of a second after RCV's (#5532). A character actor takes no part until it is invited, so seeding it there costs the story nothing.
Extends: DEMOMA-19-024

RCV Embargo Scenario (Reporter + Coordinator + Vendor, deliberate termination)

Specifies the rcv-embargo demo scenario: a 3-party CVD case with Reporter (R), Coordinator (C), and Vendor (V), exercising embargo lifecycle variations (b) post-submission negotiation and (e) deliberate early termination. After report submission and case setup, R proposes an embargo (EP). Case creation has already activated the default embargo (EP-04-001), so the case is at EM.ACTIVE before R proposes and R's proposal revises that embargo (ACTIVE → REVISE). V and C accept the Invite; C, as Case Owner, activates the revision (EC), returning EM to ACTIVE with the revision as the active embargo and all three parties as signatories to it. The fix lifecycle then proceeds. Before the natural embargo window expires, C deliberately terminates the embargo (ET), advancing EM to EXITED. The case continues to the normal P-transition and closure sequence. This scenario is the first to exercise: (a) embargo proposal initiated after report submission (variation b), (b) the full EV→EC→ET arc (propose, activate, terminate without a further revision), (c) each party's consent row for the revised embargo passing through INVITED → AGREED (signatory to the active embargo) for all three parties.

Trigger: Scenario Start — rcv-embargo

ID Priority Requirement Related
DEMOMA-20-001 MUST The rcv-embargo scenario file MUST be implemented at vultron/demo/scenario/rcv_embargo_demo.py.

The scenario registry derives the script path, the invariant harness path and the narrative path from the scenario name (ADR-0098, DEMOCI-11-003). Discovery does not find a script outside the scenario package, and a script in that package with a different name fails registration. The fixed path keeps the registered rcv-embargo scenario and its files together.
DEMOMA-20-002 MUST This codebase MUST provide an exchange helper demo_propose_and_activate_embargo in vultron/demo/exchange/. It takes (reporter, coordinator, vendor, case). Each actor argument is an ActorSession (DEMOMA-26-007), and case is the VulnerabilityCase.

One helper runs the relayed sequence the same way in the rcv-embargo and rcvv-embargo scenarios (DEMOMA-17-001), so both scenarios test the same protocol steps. Each actor is an ActorSession because a trigger addresses an actor as well as its container.
Refines: DEMOMA-17-001
Uses definition from: DEMOMA-26-007
DEMOMA-20-014 MUST demo_propose_and_activate_embargo MUST run the relayed propose-and-activate sequence (EP-09). First, the reporter posts trigger_propose_embargo, which sends the proposal to the CASE_MANAGER. Then the coordinator and the vendor each poll their own replica for the Invite(EmbargoEvent) the CASE_MANAGER relays to them. Each posts trigger_accept_embargo. The coordinator's answer, as Case Owner, activates the embargo, and the vendor's answer records its consent. Last, the helper polls every replica for em_state == EM.ACTIVE. No participant polls for another participant's message.

The CASE_MANAGER relays every embargo proposal and records each step (ADR-0113). Each participant then reads the relayed Invite(EmbargoEvent) from its own replica. A participant that polled for another's message would depend on an activity it was never sent.
Extends: DEMOMA-20-002
DEMOMA-20-003 MUST This codebase MUST provide an exchange helper demo_terminate_embargo in vultron/demo/exchange/. It takes (terminating, case) and posts trigger_terminate_embargo. terminating is the ActorSession (DEMOMA-26-007) of any signatory participant that may terminate the embargo.

The terminate-embargo exchange is a single-actor trigger that can be reused by any scenario exercising variation (e). Keeping it in vultron/demo/exchange/ (not inline in the scenario file) satisfies DEMOMA-17-001. Restricting assertions to the terminating actor's EM state keeps the helper side-effect-free with respect to peer-replica polling, which varies by scenario topology.
Refines: DEMOMA-17-001
Uses definition from: DEMOMA-26-007
DEMOMA-20-004 MUST The rcv-embargo scenario MUST be registered in the scenario registry under the name rcv-embargo. The CLI generates the rcv-embargo sub-command from the registry (DEMOCI-11-011), consistent with the naming convention of existing scenario commands.

Each scenario has one CLI sub-command, which the CLI builds from the registry, so a developer can run it by name (DC-01-001, DEMOCI-11-011). The rcv-embargo name tells the reader that this scenario is about the embargo lifecycle. It also keeps the name different from the base rcv scenario (DEMOMA-12).
See also: DEMOCI-11-011 — descriptive: names the registration the scenario then has
DEMOMA-20-005 MUST The rcv-embargo scenario MUST be registered with in_pr_set=True (DEMOCI-11-001). Its generated .github/demo-scenarios.json entry (DEMOCI-11-004) then carries "full_suite_only": false, so it runs on every PR.

The embargo lifecycle is a core part of the protocol, so a defect in it must be found on the pull request that causes it. A scenario that runs only in the full suite finds that defect later, after the pull request merges. A scenario in the PR set runs on each pull request that changes code the demos use.
Refines: DEMOCI-11-001
See also: DEMOCI-11-004 — descriptive: names the registration the scenario then has
DEMOMA-20-015 MUST The CI devlogs directory for the rcv-embargo run MUST use the scenario-role names reporter, coordinator, vendor and case-actor.

Scenario-role names in devlogs match the names used in scenario code. A reader who looks for an actor's log finds it under the name the scenario gives that actor.
DEMOMA-20-006 MUST The rcv-embargo invariant harness MUST verify that the case ledger records the embargo proposal, the owner's acceptance and the termination, in that order. It checks the semantic types the CASE_MANAGER commits for these acts.

The invariants confirm that the ledger records the proposal, the acceptance by the Case Owner and the termination, and in that order. A run that ends without an error does not show this.
Extends: DEMOMA-16-016
DEMOMA-20-016 MUST The rcv-embargo invariant harness MUST take its semantic type strings from the CASE_MANAGER's commit path in the code, not from a hand-written list.

If the test listed the type strings by hand, a rename in the code would leave it checking for strings that do not occur. Strings read from the code change with the code.
Extends: DEMOMA-20-006
DEMOMA-20-007 MUST The rcv-embargo scenario MUST be structured with the following steps executed in order: (1) report_submission, (2) embargo_proposal, (3) fix_lifecycle, (4) embargo_termination, (5) publication, (6) case_closure, and (7) dump_case_ledgers.

The structure mirrors prior RCV/RVCV scenarios while inserting embargo lifecycle steps between report setup and fix-lifecycle. The scenario is written as composition (DEMOMA-20-013), so the steps are the fragments of its story rather than phase functions of its own, and every step name but the dump is still the label its EM-state assertion carries (DEMOMA-20-008). The dump is the harness's, and has no EM state of its own to assert.

ECA Details

Preconditions

- All four containers running (Reporter, Coordinator, Vendor, CaseActor); all actors seeded and cross-registered; no embargo in force.

Steps

1. [reporter] report_submission phase — POST submit-report trigger to the Coordinator, which engages the case and invites the Vendor → the case exists on every replica; EM has no active embargo; no participant holds a consent row for an embargo
2. [reporter] embargo_proposal phase — call demo_propose_and_activate_embargo (DEMOMA-20-002): R posts trigger_propose_embargo to the CASE_MANAGER; C and V answer the relayed Invites with trigger_accept_embargo → em_state == EM.ACTIVE on every replica after the ledger fan-out and R, C and V are each a signatory to the active embargo (DEMOMA-20-009)
3. [demo-script] fix_lifecycle phase — advance the Vendor through the fix lifecycle → the fix lifecycle completes with the embargo still ACTIVE; the EM state is asserted before the next phase begins (DEMOMA-20-008)
4. [coordinator] embargo_termination phase — call demo_terminate_embargo (DEMOMA-20-003), posting trigger_terminate_embargo before the window expires → em_state == EM.EXITED on the CASE_MANAGER's canonical case (DEMOMA-20-011)
5. [demo-script] publication phase — drive the P-transition for each participant → PXA advances to Pxa on every replica
6. [demo-script] case_closure phase — close the case on every participant → RM.CLOSED for every participant in the CASE_MANAGER's store; each participant's replica ends at the entries recording its own closure (CM-23-004)
7. [demo-script] dump_case_ledgers phase → one case-ledger JSONL artifact per actor under devlogs/rcv-embargo/, recording the proposal, the owner's acceptance and the termination (DEMOMA-20-006)

Postconditions

- EM.EXITED after a deliberate termination (variation e, DEMOMA-20-011); every participant at RM.CLOSED, which the universal Invariant 7 check (test_invariant_7_log_terminates_all_rm_closed) asserts for every scenario rather than this group. Nothing beyond those is restated here — see DEMOMA-19-014's postcondition for why.

DEMOMA-20-008 MUST After each phase of the rcv-embargo scenario, the scenario MUST assert the expected EM state before proceeding to the next phase.

Phase-boundary EM assertions catch regressions where an embargo trigger silently fails and the scenario continues in an unexpected state.
DEMOMA-20-009 MUST After completing the propose-activate sequence, demo_propose_and_activate_embargo MUST assert em_state == EM.ACTIVE on the coordinator's case replica and that R, C and V are each a signatory to the active embargo (their consent row for it is AGREED).

These post-conditions confirm that all three parties successfully enrolled in the embargo before the scenario advances.
DEMOMA-20-010 MUST The demo_propose_and_activate_embargo helper MUST use demo_step and demo_check for all assertions, consistent with existing exchange helpers.

Using the shared assertion utilities keeps failure reporting consistent across all exchange helpers.
DEMOMA-20-011 MUST After delivery of trigger_terminate_embargo, demo_terminate_embargo MUST poll the CASE_MANAGER's canonical case for em_state == EM.EXITED and assert it using demo_check.

The CASE_MANAGER decides and commits the termination. The replica of the terminating actor changes only when the CASE_MANAGER announces that commit (EP-09-008). A read of that replica just after delivery can show the old state. A poll of the canonical case shows that the teardown was committed before the helper returns.
DEMOMA-20-012 MUST demo_terminate_embargo MUST NOT assert PEC states for other participants; PEC propagation is asynchronous and belongs in scenario-level phase assertions, not in the exchange helper.

Asserting peer PEC states in the exchange helper introduces a race condition; propagation timing varies by topology and scenario.
DEMOMA-20-013 MUST The rcv-embargo story MUST start with the shared "the Reporter proposes an embargo" opening and continue from the Vendor's decision to report the fix ready.

That opening nests the one RCV and RCV-reject start with and carries on through the Vendor's acceptance, the default embargo's confirmation, the Reporter's revision of it and the note thread that follows, which rcvv-embargo tells identically (DEMOMA-21-015). Each shared stretch is one copy of the code, so the two recordings agree to the vendor-after-embargo branch point byte for byte, as every pair that shares a prefix does (DEMOCI-11-017, DEMOCI-11-018).
Refines: DEMOMA-17-001

RCVV Embargo Scenario (Reporter + Coordinator + V1 + V2, revision and accidental collapse)

Specifies the rcvv-embargo demo scenario: a 4-party CVD case with Reporter (R), Coordinator (C), Vendor1 (V1), and Vendor2 (V2), exercising embargo lifecycle variations (b) post-submission negotiation, (c) revision during active embargo (EV→EC), (f) deliberate notification delay for V2 (late invitation simulating a short-deadline vendor), and (d) accidental collapse via CS.P. After R proposes and C accepts an initial embargo (EP→EA), EM reaches ACTIVE with R, C, and V1 as signatories. C then proposes a revision (EV), V1 accepts the revision Invite, C activates the revision (EC), and EM returns to ACTIVE with updated terms. V2 is not invited until after the revision is accepted, simulating a coordinator holding off on inviting a short-deadline vendor until the embargo window is near its close. V2 accepts the case invite and becomes a signatory. Finally, R publishes (CS.P fires), triggering ThreatTerminationBranchNode which auto-terminates the embargo (EM→EXITED). This scenario is the first to exercise: (a) an embargo revision cycle (EV→EC arc), (b) a late-invitee V2 joining an active embargo (consent row INVITED→AGREED after EM.ACTIVE), (c) accidental embargo collapse via external P-event rather than deliberate termination.

Trigger: Scenario Start — rcvv-embargo

ID Priority Requirement Related
DEMOMA-21-001 MUST The rcvv-embargo scenario file MUST be implemented at vultron/demo/scenario/rcvv_embargo_demo.py.

The scenario registry derives the script path, the invariant harness path and the narrative path from the scenario name (ADR-0098, DEMOCI-11-003). Discovery does not find a script outside the scenario package, and a script in that package with a different name fails registration. The fixed path keeps the registered rcvv-embargo scenario and its files together.
DEMOMA-21-002 MUST This codebase MUST provide an exchange helper demo_propose_embargo_revision in vultron/demo/exchange/. It takes (proposing, accepting, owner, case), and each of the first three arguments is an ActorSession (DEMOMA-26-007).

One shared helper holds the relayed revision sequence, so a scenario does not repeat the steps in its own module (DEMOMA-17-001). Each actor is an ActorSession because a trigger addresses an actor as well as its container.
Refines: DEMOMA-17-001
Uses definition from: DEMOMA-26-007
DEMOMA-21-017 MAY The owner argument of demo_propose_embargo_revision MAY be the same session as its proposing argument.

In rcvv-embargo the Coordinator proposes the revision and, as Case Owner, also decides it. The CASE_MANAGER does not invite the proposer (EP-09-002), so one session can play both parts.
DEMOMA-21-018 MUST demo_propose_embargo_revision MUST run the relayed revision sequence (EP-09). First, proposing posts trigger_propose_embargo_revision, which sends the proposal to the CASE_MANAGER (canonical em_state: ACTIVE → REVISE at the manager). Then accepting polls its own replica for the relayed Invite(EmbargoEvent) and posts trigger_accept_embargo. That answer records its consent and moves no EM state. Then owner posts trigger_accept_embargo. As the Case Owner's answer, it activates the revision (canonical em_state: REVISE → ACTIVE). Last, the helper polls every replica for em_state == EM.ACTIVE.

The CASE_MANAGER relays every embargo revision, and only the answer of the Case Owner decides it (ADR-0113). An answer from another participant records its consent. Accepting a revision uses the same trigger_accept_embargo endpoint as accepting a proposal, so no new endpoint is needed.
Extends: DEMOMA-21-002
DEMOMA-21-003 MUST The v2_late_invite phase of rcvv-embargo MUST invite V2 to the case only after the embargo revision (phase 3) is complete and em_state is confirmed ACTIVE.

Inviting V2 after the revision is complete — rather than before — is the defining characteristic of variation (f): the coordinator delays notification of a short-deadline vendor until the embargo terms are settled. The invitation reaches V2 through normal delivery, never by a post from the scenario to its inbox (DEMOMA-00-002).
DEMOMA-21-019 MUST On receiving the case invite in the rcvv-embargo scenario, V2 MUST accept the Active Embargo and become a signatory to it. Its consent row for the embargo is then AGREED.

V2 accepts the embargo in force when it joins, so it is enrolled before CS.P collapses the embargo. The ledger then records V2's consent at the time of the collapse without doubt.
Extends: DEMOMA-21-003
DEMOMA-21-004 MUST The accidental_collapse phase of rcvv-embargo MUST trigger the P-transition by calling actor_notifies_published on the reporter's client.

Variation (d) specifically exercises the accidental/automatic embargo collapse path rather than the deliberate termination (ET) path. ThreatTerminationBranchNode fires when CS.P is detected on the CaseActor, emitting the EM termination activity automatically. Using actor_notifies_published from vultron/demo/helpers/actions.py exercises this code path end-to-end.
DEMOMA-21-020 MUST After the P-transition of DEMOMA-21-004, the rcvv-embargo scenario MUST poll for the CaseActor's embargo teardown (EM.EXITED via ThreatTerminationBranchNode). The poll comes before the scenario asserts em_state == EM.EXITED on the coordinator's replica.

The CaseActor commits the teardown in a background task after it sees CS.P. A check of the coordinator's replica just after the trigger can still show the old state. A poll for the teardown first makes the check wait for its cause.
Extends: DEMOMA-21-004
DEMOMA-21-005 MUST The rcvv-embargo scenario MUST be registered in the scenario registry under the name rcvv-embargo. The CLI generates the rcvv-embargo sub-command from the registry (DEMOCI-11-011), consistent with the naming convention of existing scenario commands.

Each scenario has one CLI sub-command, so a developer can run it by name (DC-01-001). The CLI builds that sub-command from the registry (DEMOCI-11-011). Without the registration, the scenario can run only through its module, and the CLI does not show that the scenario exists.
See also: DEMOCI-11-011 — descriptive: names the registration the scenario then has
DEMOMA-21-006 MUST The rcvv-embargo scenario MUST be registered with in_pr_set=True (DEMOCI-11-001). Its generated .github/demo-scenarios.json entry (DEMOCI-11-004) then carries "full_suite_only": false, so it runs on every PR.

The revision and the collapse of an embargo are core parts of the protocol, so a defect in them must be found on the pull request that causes it. A scenario that runs only in the full suite finds that defect later, after the pull request merges. A scenario in the PR set runs on each pull request that changes code the demos use.
Refines: DEMOCI-11-001
See also: DEMOCI-11-004 — descriptive: names the registration the scenario then has
DEMOMA-21-021 MUST The CI devlogs directory for the rcvv-embargo run MUST use the scenario-role names reporter, coordinator, vendor, vendor2 and case-actor.

Scenario-role names in devlogs match the names used in scenario code. A reader who looks for an actor's log finds it under the name the scenario gives that actor.
DEMOMA-21-007 MUST The rcvv-embargo invariant harness MUST verify that the case ledger records four acts. They are the embargo proposal, the owner's acceptance, the revision proposal and the owner's acceptance of the revision. It checks the semantic types the CASE_MANAGER commits for these acts.

The scenario-specific invariants confirm all four embargo-variation protocol paths were exercised and recorded: EP (b), EV (c), EC (c), and auto-collapse via CS.P (d). The late-joiner backfill check for V2 verifies that the ledger synchronization worked correctly when V2 joined mid-scenario after an embargo revision.
Extends: DEMOMA-16-017
DEMOMA-21-022 MUST The rcvv-embargo invariant harness MUST take its semantic type strings from the CASE_MANAGER's commit path in the code, not from a hand-written list.

If the test listed the type strings by hand, a rename in the code would leave it checking for strings that do not occur. Strings read from the code change with the code.
Extends: DEMOMA-21-007
DEMOMA-21-008 MUST The rcvv-embargo scenario MUST be structured with the following steps executed in order: (1) report_submission, (2) embargo_proposal, (3) embargo_revision, (4) v2_late_invite, (5) fix_lifecycle, (6) accidental_collapse, (7) case_closure, and (8) dump_case_ledgers.

The ordering reflects the temporal protocol constraints: revision requires an ACTIVE embargo; V2 late-invite simulates a short-deadline vendor held back until terms are settled. The scenario is written as composition (DEMOMA-21-015), so the steps are the fragments of its story rather than phase functions of its own, and every step name but the dump is still the label its EM-state assertion carries (DEMOMA-21-009). The dump is the harness's, and has no EM state of its own to assert.

ECA Details

Preconditions

- All five containers running (Reporter, Coordinator, V1, V2, CaseActor); all actors seeded and cross-registered; V2 not yet invited.

Steps

1. [reporter] report_submission phase — POST submit-report trigger to the Coordinator, which engages the case and invites V1 → the case exists on every replica with R, C and V1 as participants
2. [reporter] embargo_proposal phase — call demo_propose_and_activate_embargo: R posts trigger_propose_embargo, C posts trigger_accept_embargo → em_state == EM.ACTIVE with R, C and V1 each a signatory to the active embargo
3. [coordinator] embargo_revision phase — call demo_propose_embargo_revision (DEMOMA-21-002): C posts trigger_propose_embargo_revision to the CASE_MANAGER (canonical ACTIVE → REVISE); V1 answers the relayed Invite with trigger_accept_embargo (consent); C, as Case Owner, posts trigger_accept_embargo (canonical REVISE → ACTIVE) → em_state returns to EM.ACTIVE with the revised terms on every replica after the ledger fan-out
4. [coordinator] v2_late_invite phase — invite V2 only after the revision is complete and em_state is confirmed ACTIVE (DEMOMA-21-003) → V2 accepts the case invite and the Active Embargo, becoming a signatory to it (DEMOMA-21-012)
5. [demo-script] fix_lifecycle phase — advance V1 and V2 through the fix lifecycle → the fix lifecycle completes for V1 and V2; the embargo stays ACTIVE until the accidental collapse in phase 6
6. [reporter] accidental_collapse phase — call actor_notifies_published on the reporter's client to fire CS.P; trigger_terminate_embargo MUST NOT be called (DEMOMA-21-004, DEMOMA-21-014) → CaseActor emits the embargo teardown via ThreatTerminationBranchNode and em_state == EM.EXITED on the Coordinator's replica
7. [demo-script] case_closure phase — close the case on every participant → RM.CLOSED for every participant in the CASE_MANAGER's store; each participant's replica ends at the entries recording its own closure (CM-23-004)
8. [demo-script] dump_case_ledgers phase → one case-ledger JSONL artifact per actor under devlogs/rcvv-embargo/, recording the proposal, the owner's acceptance, the revision proposal and its acceptance (DEMOMA-21-007)

Postconditions

- EM.EXITED as an automatic consequence of CS.P rather than a deliberate termination (variation d, DEMOMA-21-004); every participant at RM.CLOSED, which the universal Invariant 7 check (test_invariant_7_log_terminates_all_rm_closed) asserts for every scenario rather than this group. Nothing beyond those is restated here — see DEMOMA-19-014's postcondition for why.

DEMOMA-21-009 MUST After phases 2, 3, 4, and 6 of the rcvv-embargo scenario, the scenario MUST assert the expected EM state before proceeding to the next phase.

Phase-boundary EM assertions catch silent failures where an embargo trigger fires but the state machine does not advance.
DEMOMA-21-010 MUST After the revision sequence, demo_propose_embargo_revision MUST poll the CASE_MANAGER's canonical case and the accepting client's replica for em_state == EM.ACTIVE and assert both using demo_check.

A check for ACTIVE after the revision shows that the Case Owner decided and that the embargo did not stay in REVISE. The canonical case shows that the CASE_MANAGER committed the decision. The replica of the accepting client shows that the ledger update reached a participant that is not the Case Owner.
DEMOMA-21-011 MUST The demo_propose_embargo_revision function MUST be importable from vultron/demo/exchange/.

The exchange package is where every scenario finds its embargo helpers. A revision helper outside it would be a second place to look for the same kind of exchange.
DEMOMA-21-023 MUST NOT The demo_propose_embargo_revision function MUST NOT duplicate the propose-and-activate logic already in demo_propose_and_activate_embargo (DEMOMA-20-002).

Reusing the activate path prevents divergence between the propose-and-activate and revision helpers when the embargo lifecycle nodes change.
Uses definition from: DEMOMA-20-002
DEMOMA-21-012 MUST The rcvv-embargo scenario MUST assert that V2 is a signatory to the active embargo before proceeding to the fix_lifecycle phase.

V2 must be fully enrolled in the embargo before it is accidentally collapsed by CS.P, making the ledger record unambiguous about V2's consent at time of collapse.
DEMOMA-21-013 MUST The rcvv-embargo scenario MUST use polling helpers (not post_to_inbox_and_wait) to detect the invite in V2's inbox, consistent with DEMOMA-00-002.

DEMOMA-00-002 requires that the demo orchestrator never post directly to another actor's inbox; polling ensures the invite arrives via the normal routing path.
Refines: DEMOMA-00-002
DEMOMA-21-014 MUST NOT The accidental_collapse phase of rcvv-embargo MUST NOT call trigger_terminate_embargo directly.

Calling trigger_terminate_embargo directly would test variation (e), the deliberate termination, instead of variation (d).
DEMOMA-21-024 MUST In the accidental_collapse phase of rcvv-embargo, the embargo collapse MUST arrive as an automatic consequence of CS.P, not as a deliberate termination.

Variation (d) specifically exercises the automatic embargo collapse path via ThreatTerminationBranchNode. A collapse that a participant starts on purpose would leave that path untested.
Extends: DEMOMA-21-014
DEMOMA-21-015 MUST The rcvv-embargo story MUST start with the shared "the Reporter proposes an embargo" opening (DEMOMA-20-013) and continue from Vendor1's revision.

The revision cycle is the first thing this scenario tells differently, so everything before it is one copy of the code shared with rcv-embargo, so the two recordings agree up to the vendor-after-embargo branch point byte for byte, as every pair that shares a prefix does (DEMOCI-11-017, DEMOCI-11-018). Naming the opening here keeps this group a whole story.
Refines: DEMOMA-17-001
Uses definition from: DEMOMA-20-013
DEMOMA-21-016 MUST Vendor2's actor MUST be seeded by the step that invites it, not by the shared opening (DEMOMA-21-015).

The shared opening writes the same records in every scenario that starts with it, which is what makes their recordings agree (DEMOCI-11-018). Each actor and peer record written before the case exists is one more read of the recording clock, so seeding four containers in the opening stamped this scenario's first ledger entry a sixth of a second after rcv-embargo's (#5532). Vendor2 takes no part until it is invited, so seeding it there costs the story nothing.
Extends: DEMOMA-21-015

Causal Gating and Scenario Narratives

ID Priority Requirement Related
DEMOMA-22-001 MUST Every scenario script under vultron/demo/scenario/ MUST gate each asynchronous protocol boundary on a causal precondition satisfying EDF-06-001 through EDF-06-003 before driving the next trigger.

A trigger commits its local change and returns before its activity is delivered. The receiving actor commits its own change later. A step that runs before its cause is visible operates on state that does not exist yet. A rule for one scenario does not stop the next scenario from making the same mistake, so the rule applies to every scenario (ADR-0058).
Refines: EDF-06-001
Refines: EDF-06-003
DEMOMA-22-002 MUST A causal gate predicate is a reusable function that polls or scans an actor's own state to decide whether a precondition holds. This codebase MUST define each causal gate predicate in vultron/demo/helpers/.

This applies DEMOMA-17-001 (extract before reuse) to gate predicates. The rule does not move the demo_gate context manager: DEMOCI-01-007 places it in vultron/demo/utils/failures.py with demo_step and demo_check. Only the functions that read actor state live in the helpers.
Refines: DEMOMA-17-001
DEMOMA-22-008 MUST NOT A scenario module MUST NOT define its own polling or retry loop.

A polling loop written in a scenario module is a copy that the next fix does not reach, so a defect fixed in one scenario stays in another. When every loop lives in the helpers, one fix reaches every scenario (DEMOMA-17-001).
Extends: DEMOMA-22-002
DEMOMA-22-003 MUST Each demo scenario MUST have a narrative page under docs/topics/scenarios/ that tells, in domain terms alone, how the case moves through the CVD process. The page names no implementation detail, such as an endpoint, a helper function or the container topology.

A narrative written in domain terms is an independent statement of what the protocol is supposed to accomplish. Because it is written without reference to the implementation, it can disagree with the implementation — which is precisely what makes it usable as a conformance oracle rather than a restatement of the code.
DEMOMA-22-009 MUST Each step of a scenario narrative MUST state the antecedent that causes it.

A step that names its cause states the causal claim that a causal edge records (DEMOMA-22-004). A step without one reads as a sequence, and a reader cannot tell a cause from a position in the script (ADR-0058).
Extends: DEMOMA-22-003
DEMOMA-22-004 MUST Each scenario narrative MUST carry a machine-readable list of causal edges.

Prose alone drifts silently from the code it describes. A structured edge list is the part of the narrative a test can check, and it forces the author to state the causal claim precisely enough to be falsifiable.
DEMOMA-22-010 MUST Each causal edge MUST name its antecedent event, its consequent event and the actor that commits the consequent.

An edge is a causal claim only when it names both events. The actor that commits the consequent is the one field that ties the edge to a ledger entry, so a check can tell a consequent committed by the wrong actor from the right one.
Extends: DEMOMA-22-004
DEMOMA-22-011 MUST The actor label of a causal edge MUST name the actor recorded on the consequent's ledger entry, the literal emitter of the activity. For an activity the CASE_MANAGER emits on a participant's behalf, such as every invite_actor_to_case, the label names the CASE_MANAGER (CM-24-001, PCR-08-007).

The CASE_MANAGER commits every ledger entry, so "the actor that commits" must be read off the entry. The actor field names the literal emitter. For a delegated emission the requesting participant is recoverable from the entry's attributedTo (CM-24-002), not from the label, so the label stays one value that a check can compare.
Refines: DEMOMA-22-010
Uses definition from: CM-24-001
Uses definition from: PCR-08-007
DEMOMA-22-005 MUST The invariant harness MUST assert that each causal edge in a scenario's narrative appears in that scenario's case ledger, with the antecedent's log index first.

The case ledger records log_index in causal order (ADR-0079, CLP-14-001) and the invariant harness already reads the per-scenario ledger dumps, so checking declared causality against observed causality needs no new instrumentation. This is what converts the narrative from documentation into a conformance check.
DEMOMA-22-012 MUST The invariant harness MUST check the actor tag of each causal edge against the ledger. It counts as the consequent only an entry whose recorded actor resolves to the edge's consequent_actor through the scenario's dump manifest.

An order check alone passes when some entry of the right type follows the antecedent, even one committed for another actor. Resolving the recorded actor through the dump manifest makes the tag part of the claim the harness checks.
Extends: DEMOMA-22-005
DEMOMA-22-013 MUST The invariant harness MUST fail a causal edge with no consequent entry whose recorded actor matches its tag, or whose recorded actor the manifest lacks.

An edge that the harness cannot match to a tagged entry is a claim with no evidence. A pass in that case would turn a wrong tag, or an actor missing from the dump, into a silent success.
Extends: DEMOMA-22-005
DEMOMA-22-006 MUST A change to a scenario's protocol flow MUST update that scenario's narrative and its declared causal edges in the same pull request.

If the flow changes and the narrative does not, the causal-edge check can fail. The easy fix is then to make the check weaker, and the narrative then checks nothing. A change to both in one pull request makes a protocol change visible as a narrative change, where a reviewer can judge it.
DEMOMA-22-007 MUST Every wait_for_* call in a scenario script MUST be wrapped in either demo_gate (when the wait is a causal precondition for a subsequent step) or demo_check (when the wait is temporal or a non-gating post-hoc verification). Bare unwrapped wait_for_* calls are prohibited.

A bare call raises AssertionError directly on timeout, bypassing the demo harness's failure accumulator. Earlier demo_check failures accumulated in the same run are lost, and downstream steps do not receive the structured skip that demo_gate provides — the exception terminates the scenario with no record of what preceded the failure. demo_gate and demo_check are the two sanctioned wrappers; using them consistently keeps the failure record complete and the control flow explicit.
Extends: DEMOMA-22-001 — DEMOMA-22-001 requires causal gating at every async boundary; this requirement closes the loophole of bare calls that appear to gate but do not integrate with the failure accumulator.
Implements: EDF-06-005 — Wrapping a causal wait in demo_gate is how an unmet gate stops the dependent steps (EDF-06-005).
DEMOMA-22-014 MUST Every StoryProp declared under vultron/demo/ MUST have at least one step that keeps it and at least one step that reads it.

A prop is how a flat composed story carries the causal gate a hand-placed scenario carried by nesting: the step that performs an act keeps the prop inside that act's own demo_gate, and the step whose precondition is that act reads it first, so a failed act stops the story (DEMOCI-01-011). Keeping one guarantees nothing by itself: a prop kept by the roster gate and read by nobody left both owner-decision continuations running after a timed-out roster, with every test green (#5535, #5598).
Derives from: DEMOCI-01-011 — A prop is the flat-sequence form of the nesting a demo_gate gives a hand-placed scenario, so the prop rule is a consequence of DEMOCI-01-011's gate having to reach a dependent step in another fragment, not a narrower case of it.
Extends: DEMOMA-22-001
DEMOMA-22-015 MUST A story step's StoryProp parameter under vultron/demo/ MUST be keyword-only.

A prop is handed over by name, so a call site that miscounts cannot land a cast part or a label in its place, and a *args slot cannot be named at all. It binds the keep side as well as the read side, because the slot is what a reader of the call sees. A step's parameter, not every parameter of the type: StoryState.keep and kept take the prop positionally and are the primitives every site calls (#5598).
Extends: DEMOMA-22-014
DEMOMA-22-016 MUST A step that reads a StoryProp it is handed MUST take it with no default and with an annotation that does not admit None.

The read has to be structural rather than remembered: a continuation that cannot be assembled without being told which act it depends on cannot be assembled without the gate. Relaxing it to joined: StoryProp[str] &#124; None = None behind an if joined is not None: guard left the suite green, because every call site passed the prop anyway (#5535). ADR-0058's "no modified calling convention" answers this for a hand-placed scenario, whose nesting carries the gate; a flat story has none (#5598).
Extends: DEMOMA-22-014
DEMOMA-22-017 MAY A step that only keeps under a StoryProp parameter MAY make that parameter optional.

An absent prop on the keep side means no later act depends on this gate, not that a gate is missing, so DEMOMA-22-016's obligation does not reach it: invitee_joins_the_case keeps a prop only for a joiner some later act presupposes, and runs a plain demo_check for the rest (DEMOCI-01-011).
Refines: DEMOMA-22-016
DEMOMA-22-018 MUST Each StoryProp declared under vultron/demo/ MUST be constructed as a module-level assignment to one name.

The constant is how every site names the prop, so a construction no site can name is checked by nothing: one built in a function, a class body or a collection is reachable by nothing. This is what makes the enumeration complete rather than best-effort — every construction under vultron/demo/ is then either a subject the wiring arms reach or a failure of this one (#5598).
Extends: DEMOMA-22-014
DEMOMA-22-019 MUST Each StoryProp declared name MUST be declared exactly once under vultron/demo/.

The name is the key StoryState keeps the artifact under, and a composed scenario draws fragments from more than one family's module, so a second declaration spelling an existing name would have the two families overwrite each other's artifact. Worse when their types differ: the read checks the type it got back, so the collision is reported as the story having no such artifact yet — the message for a fragment placed before the one that makes what it reads.
Extends: DEMOMA-22-020
DEMOMA-22-020 MUST Each StoryProp declared under vultron/demo/ MUST give its declared name as a string literal.

The declared name is the key StoryState keeps the artifact under and the words every failure message uses, so a name given as a variable leaves the uniqueness check nothing to group and every message nothing to say. Split from DEMOMA-22-018 because the two are unrelated properties of a declaration, verified by their own arms and retired apart (#5598).
Refines: DEMOMA-22-018
DEMOMA-22-021 MUST A story step under vultron/demo/ that takes a StoryProp parameter MUST keep under it or read it.

The parameter is how a step says which earlier act it depends on, so a step that does nothing with the prop has the signature of a gated step and the body of an ungated one — the #5535 relaxation written the other way round. DEMOMA-22-014 cannot see it: keep and read sites are counted per prop, not per (prop, step) pair, so a second step reading the same prop hides it (#5598).
Extends: DEMOMA-22-014

Shared Scenario Harness

ID Priority Requirement Related
DEMOMA-23-001 MUST Every run_<name>_demo() orchestrator MUST run its story inside the shared scenario_harness("<demo-name>") context manager from vultron.demo.helpers.harness. That harness resets the failure accumulator, always dumps the case ledgers, and only then asserts demo success.

Every scenario must reset the failure record, dump the ledgers, and then assert success, in that order. When each scenario does this itself, the order can differ. One shared harness does the three steps in the same order for every scenario and keeps the real cause of a failure.
Implements: DEMOCI-10-001
Refines: DEMOMA-17-001
DEMOMA-23-010 MUST NOT A scenario's main() MUST NOT wrap the run in try: ... finally: assert_demo_success().

A finally: assert_demo_success() in main() is a second owner of the failure accumulator. It can assert before the harness dumps the ledgers, and it replaces the real exception with a generic DemoFailureError.
Extends: DEMOMA-23-001
DEMOMA-23-002 MUST A scenario's dump step MUST be a thin wrapper over vultron.demo.helpers.ledger_dump.dump_case_ledgers(), declaring only that scenario's dump targets (actor name, client, route key, and any fallback).

The export loop is the same for every scenario. A copy of it in each scenario module is the duplication that DEMOMA-17-001 forbids. Every scenario is written as composition, so the step is the dump= story fragment its cast opening was built with (DEMOCI-11-019).
Refines: DEMOMA-17-001
DEMOMA-23-009 MUST Per-actor fetching, 404 handling, JSONL writing and manifest writing MUST live in the shared dump helper, not in a scenario module.

The scenario keeps only its own participant map and the helper keeps the mechanics, so each fact is in one place and a defect in the export is fixed once (DEMOMA-23-002).
Derives from: DEMOMA-23-002
DEMOMA-23-003 MUST A scenario MUST register its dump with the harness as soon as a case exists. That is the first instant there is anything to dump, and not the end of the run.

The harness can only dump what it has been given. Registering the dump at the first point where a case exists is what makes every later failure survivable: the ledgers that existed at the moment of failure are still exported. Every scenario calls state.open_case(...), which arms the dump= fragment it was built with (DEMOCI-11-019).
Implements: DEMOCI-10-001
DEMOMA-23-004 SHOULD When a scenario body raises, the harness SHOULD attach the accumulated demo_step/demo_check failures to the propagating exception as notes rather than raising DemoFailureError in their place.

The accumulated soft failures are usually downstream consequences of the exception, so they are context, not the cause. Attaching them as notes keeps both: the reader sees the failure that stopped the run and every check that had already failed.
DEMOMA-23-005 MUST This codebase MUST perform every wait for replicas to reach contiguous ledger coverage of an authority's tail through a shared helper in vultron/demo/helpers/sync/. The helper reads the authority tail and polls each replica. It applies the named ledger-coverage timeout constants from vultron/demo/helpers/polling/: a default budget and a wider late-joiner budget. Neither budget is below one that a scenario carried before the loop was shared. The helper wraps each per-replica wait in a demo context.

Every scenario waits until each replica holds the ledger of the authority, for example as the causal gate before the notes phase. A copy of this wait in each scenario lets the timeouts differ by module and by replica, and a copy can forget a timeout and use a value that is too short. One helper keeps the loop, the named timeouts and the demo context in one place.
Refines: DEMOMA-17-001
Refines: DEMOCI-01-014 — DEMOCI-01-014 requires a shared helper that encapsulates polling to perform the demo-context wrap itself; the coverage helper is such a helper.
DEMOMA-23-011 MUST This codebase MUST perform the closure-phase wait for a departed participant's replica to end at its own closure through a helper in vultron/demo/helpers/sync/.

After case closure no replica covers the authority's tail, because a closed participant is sent nothing after the entries that record its own closure (CM-23-004). The closure wait therefore checks a different end point. A shared helper keeps that check and its timeout the same in every scenario.
Extends: DEMOMA-23-005
DEMOMA-23-006 MUST NOT A module under vultron/demo/ other than the vultron/demo/helpers/sync/ package MUST NOT call or import wait_for_contiguous_ledger_coverage or _get_log_entries_for_case directly. Defining the primitive and re-exporting either name from a package __init__ are exempt.

The shared helper (DEMOMA-23-005) is useful only if every scenario calls it. A direct call to the primitive is how a copy of the coverage loop gets back into a new scenario, which is often written from an earlier one. The ban also covers helper modules, because a copy moved into a helper module is still a copy, and a check of scenario modules only cannot see it.
Derives from: DEMOMA-23-005
DEMOMA-23-007 MUST A scenario's replica sync-verification step MUST be a thin call to a shared helper in vultron/demo/helpers/sync/. It declares only the scenario's authority, replicas, late joiners, expected participant set and the replica pairs to state-check.

Keeping the scenario's facts in the scenario and the mechanics in the helper puts each fact in one place, exactly as DEMOMA-23-002 does for the ledger dump. A scenario-specific extra — the rv scenario's check that its dedicated case-actor container holds the case — follows the helper call as a separate step rather than becoming a per-scenario variant of the step's body. Every scenario is written as composition, so the step is a story fragment.
Depends on: DEMOMA-23-005
Refines: DEMOMA-17-001
DEMOMA-23-008 MUST A scenario whose ledger authority holds no ledger entries for the case MUST fail: an authority with an empty ledger is a demo failure, not a vacuous pass of the ledger checks.

Checks that iterate over the entries of the authority pass when there are no entries. An authority with no entries means that the case never reached it, or that its ledger was never read. Either way the run proved nothing, so it must fail and not pass with nothing checked.

RCVD Scenario (Reporter + Coordinator + Vendor + Deployer)

Requirements for the RCVD scenario, which exercises the Deployer role as a participant distinct from the Vendor. The Vendor develops the fix (VFd) but does not deploy it; the Deployer applies the patch in their own environment (d→D), gated on the causal precondition that at least one Vendor in the case has reached VFd state (CSB-15-004). This is the first scenario in which a DEPLOYER-only participant (holding CVDRole.DEPLOYER but not CVDRole.VENDOR) completes the fix-deployment protocol step.

Trigger: Scenario Start — rcvd

ID Priority Requirement Related
DEMOMA-24-001 MUST The RCVD scenario MUST involve five actor identities, each with its own isolated DataLayer and separate container: Reporter, Coordinator, Vendor, Deployer and CaseActor. The Coordinator holds CVDRole.CASE_OWNER throughout the scenario.

RCVD is the canonical scenario demonstrating the distinction between fix availability (Vendor's F event) and fix deployment (Deployer's D event). Five separate containers enforce true multi-container message delivery and per-actor DataLayer isolation, consistent with DEMOMA-01-001. The Coordinator as CASE_OWNER follows the RCV topology so that the Deployer role is the sole new element introduced.
Refines: DEMOMA-01-001
DEMOMA-24-009 MUST In the RCVD scenario, the CaseActor MUST run as a separate actor identity on its own container.

A CaseActor on its own container receives every activity through real delivery, as in RCV (DEMOMA-12-019). Co-located with another actor, it could see state that the protocol never delivered to it.
Extends: DEMOMA-24-001
DEMOMA-24-002 MUST In the RCVD case, the Vendor actor MUST hold CVDRole.VENDOR alone, without CVDRole.DEPLOYER.

The central protocol distinction this scenario demonstrates is that fix availability (Vendor at VFd) and fix deployment (Deployer at VFD) are separate events attributed to separate actors. A Vendor-only actor cannot hold CVDRole.DEPLOYER; CSB-15-002 would block d→D for it regardless, but the scenario MUST make this explicit through role assignment and post-milestone verification.
DEMOMA-24-010 MUST In the RCVD scenario, the Vendor's participant VFD path MUST advance to VFd (fix ready).

Fix readiness at the Vendor is the causal precondition for the Deployer's d→D transition (CSB-15-004). Without it the scenario cannot show deployment by a separate actor.
Extends: DEMOMA-24-002
DEMOMA-24-011 MUST NOT In the RCVD scenario, the Vendor's participant VFD path MUST NOT advance to VFD (fix deployed).

The scenario shows that fix availability and fix deployment are separate events of separate actors. A Vendor that reached VFD would erase that distinction, and a VENDOR-only participant has no deployer path (CSB-15-002).
Extends: DEMOMA-24-002
Derives from: CSB-15-002
DEMOMA-24-012 MUST After the fix-ready milestone, the RCVD scenario MUST verify that the Vendor is at VFd and has no VFD participant status snapshot.

Role assignment alone does not show that the Vendor stopped at VFd. A check after the milestone makes the stop visible in every run, so a regression that lets the Vendor reach VFD fails the scenario.
Verifies: DEMOMA-24-010
Verifies: DEMOMA-24-011
DEMOMA-24-003 MUST In the RCVD case, the Deployer actor MUST hold CVDRole.DEPLOYER alone, without CVDRole.VENDOR.

A DEPLOYER-only participant is the case this scenario adds. A Deployer that also held CVDRole.VENDOR could reach VFD on its own vendor path, and the scenario would not exercise the CSB-15-004 causal gate.
DEMOMA-24-013 MUST The Coordinator MUST invite the Deployer to the RCVD case only after the scenario verifies the fix-ready milestone (Vendor at VFd).

Inviting the Deployer after fix-ready ensures the causal gate (at least one VENDOR in the case at VFd, CSB-15-004) is satisfied when the Deployer attempts d→D. An earlier invite is a valid protocol scenario, but it needs a separate causal-gate check in the BT; the later invite isolates the pure-Deployer path.
Extends: DEMOMA-24-003
DEMOMA-24-004 MUST The RCVD scenario MUST exercise the causal-gate d→D path of CSB-15-004 for the DEPLOYER-only participant.

CSB-15-004 defines a new guard condition for DEPLOYER-only actors that replaces the per-participant VFD-state check used by VENDOR actors. The RCVD scenario is the primary functional test exercising this path end-to-end in a multi-container context. The scenario-level verify_fix_deployed call MUST pass the Deployer actor ID (not the Vendor actor ID) to confirm that DEMOMA-15-002 is satisfied.

ECA Details

Preconditions

- All five containers running (Reporter, Coordinator, Vendor, Deployer, CaseActor); all actors seeded and cross-registered; the Coordinator holds CVDRole.CASE_OWNER throughout (DEMOMA-24-001).

Steps

1. [reporter] POST submit-report trigger to the Coordinator, which validates and engages the case → the case exists on the Coordinator's replica; RM→ACCEPTED
2. [coordinator] invite the Vendor (CVDRole.VENDOR only) into the case → the Vendor accepts and holds no CVDRole.DEPLOYER (DEMOMA-24-002)
3. [vendor] advance the participant VFD path to VFd without deploying → Vendor VFD = VFd and no VFD participant status snapshot exists for the Vendor actor (DEMOMA-24-002); the CSB-15-004 causal precondition is now satisfied
4. [coordinator] invite the Deployer (CVDRole.DEPLOYER only) into the case, AFTER the fix-ready milestone is verified (DEMOMA-24-013) → the Deployer container is polled for the arriving invitation before the accept-case-invite trigger is driven (DEMOMA-24-018); the Deployer holds no CVDRole.VENDOR (DEMOMA-24-003)
5. [deployer] apply the patch in its own environment, driving the d→D transition → the BT permits d→D because a VENDOR participant is at VFd (DEMOMA-24-014), and blocks d→D for any participant that holds neither CVDRole.DEPLOYER nor satisfies the causal precondition (DEMOMA-24-015)
6. [demo-script] drive publication, calling verify_publicly_disclosed with the Deployer actor ID as the DEPLOYER-role participant (DEMOMA-24-016) → PXA advances to Pxa on every replica; EM.EXITED
7. [demo-script] close the case on every participant, then dump the case ledgers → RM.CLOSED for every participant in the CASE_MANAGER's store; each participant's replica ends at the entries recording its own closure (CM-23-004); one case-ledger JSONL artifact per actor under devlogs/rcvd/

Postconditions

- The final state DEMOMA-24-005 requires. Deliberately a pointer rather than a copy: -005 is the authority for that state, and a restatement here would drift from it with nothing able to tell which was current (MS-16-002).

Verifies: CSB-15-004
DEMOMA-24-014 MUST In the RCVD scenario, the BT MUST permit the Deployer's d→D transition once a VENDOR participant in the case is at VFd.

This is the permit half of the CSB-15-004 guard. A DEPLOYER-only participant has no VFD state of its own to check, so the guard reads the Vendor's fix readiness instead.
Extends: DEMOMA-24-004
DEMOMA-24-015 MUST In the RCVD scenario, the BT MUST block d→D for any participant that holds neither CVDRole.DEPLOYER nor satisfies the causal precondition.

This is the block half of the CSB-15-004 guard. A guard that only ever permits is not shown to guard anything, so the scenario exercises the refusal too.
Extends: DEMOMA-24-004
DEMOMA-24-005 MUST The RCVD scenario MUST reach a final state with Vendor VFD = VFd, Deployer VFD = VFD, EM.EXITED, and PXA = Pxa and RM.CLOSED for every participant. Its participants are the Reporter, Coordinator, Vendor, Deployer and CaseActor.

Verifying Vendor stops at VFd and Deployer reaches VFD confirms the role-separated VFD model.
DEMOMA-24-016 MUST The RCVD scenario MUST pass the Deployer actor ID to verify_publicly_disclosed as the participant with the DEPLOYER role.

Using the Deployer actor ID in verify_publicly_disclosed exercises the existing vfd_roles branch that treats DEPLOYER the same as VENDOR for public-state verification.
Extends: DEMOMA-24-005
DEMOMA-24-006 MUST The implementation of the RCVD scenario MUST register it with the scenario registry (DEMOCI-11-001) in the same PR as the scenario script, so that its generated .github/demo-scenarios.json entry (DEMOCI-11-004) runs it as its own CI matrix job and CI failures are independently reported per DEMOCI-03-003.

A scenario that is not registered has no entry in the CI matrix, so it can break without notice. Registration in the same pull request as the script gives the scenario a matrix entry from the time that it is in the repository. Its own CI job keeps its failures separate from those of other scenarios (DEMOCI-03-003).
Refines: DEMOCI-03-002
Refines: DEMOCI-11-001
See also: DEMOCI-03-003 — the consequence the statement cites (independent reporting), not a link
See also: DEMOCI-11-004 — descriptive: names the registration the scenario then has
DEMOMA-24-007 MUST The RCVD implementation MUST ship a dedicated case-ledger invariant test file, test/ci/invariants/test_rcvd_invariants.py, built on the shared invariant library.

The VFd-vs-VFD distinction for Vendor and Deployer is the central protocol claim of the RCVD scenario; without an invariant test that explicitly checks both states, a regression that lets the Vendor silently reach VFD would pass CI undetected.
DEMOMA-24-017 MUST The RCVD invariant test file MUST assert four scenario-specific checks. (1) invite_actor_to_case appears at least three times, for the Reporter, Vendor and Deployer invitations. (2) accept_invite_actor_to_case appears at least three times. (3) add_participant_status_to_participant entries show VFd, not VFD, for the Vendor and VFD for the Deployer. (4) The Deployer replica holds the full case history from genesis.

The VFd-vs-VFD distinction for Vendor and Deployer is the central protocol claim of the RCVD scenario. Without a check of both states, a regression that lets the Vendor reach VFD would pass CI undetected.
Extends: DEMOMA-24-007
DEMOMA-24-008 MUST The RCVD scenario MUST run deterministically end to end.

A run whose result depends on timing tells nothing about the code. It fails for a reason that is not a protocol defect, or it passes only when the timing is fortunate.
DEMOMA-24-018 MUST The RCVD scenario MUST poll the Deployer container for the arriving case invitation before it drives the accept-case-invite trigger, as DEMOMA-12-013 does.

The invitation reaches the Deployer container some time after the Coordinator sends it. If the demo drives the accept trigger before the invitation is there, the accept fails or answers nothing.
Refines: DEMOMA-22-001
See also: DEMOMA-12-013 — an analogy ("as ... does")

VC Scenario (Vendor self-reports; Coordinator joins as Observer)

Trigger: Scenario Start — vc

ID Priority Requirement Related
DEMOMA-25-001 MUST The VC scenario MUST involve three actor identities, each with its own isolated DataLayer and separate container: Vendor, Coordinator and CaseActor.

Separate containers exercise true multi-container message delivery. Every container the scenario needs is already in the fixed cast (DEMOCI-11-020), so no new infrastructure is required.
Refines: DEMOMA-01-001
DEMOMA-25-007 MUST In the VC scenario, the CaseActor MUST run as a separate actor identity on the dedicated case-actor container, not on the Vendor container.

Using the shared case-actor container for Vendor-owned cases matches the topology of other scenarios where a non-Coordinator actor holds CASE_OWNER. It keeps the CaseActor identity consistent across scenarios.
Extends: DEMOMA-25-001
DEMOMA-25-008 MUST docker-compose-multi-actor.yml MUST configure the Vendor with VULTRON_ACTOR__CASE_ACTOR_SERVICE_URL=http://case-actor:7999/api/v2.

The Vendor owns the VC case, so it is the actor that asks the case actor service for a CaseActor. Without this setting it cannot place the CaseActor on the dedicated case-actor container.
Implements: DEMOMA-25-007
DEMOMA-25-002 MUST In the VC scenario, Vendor MUST submit the initial vulnerability report to its own inbox using reporter_submits_report with Vendor in BOTH the reporter and receiver slots. No external Reporter actor exists; there are no interactions outside the protocol. Vendor then validates the report (RM→RECEIVED→VALID) and engages the case (RM→ACCEPTED→case created), becoming CASE_OWNER with CVDRole.VENDOR + CVDRole.CASE_OWNER.

Vendor-as-reporter means the discoverer and the responsible fixer are the same actor. Using reporter_submits_report unchanged ensures the standard RM intake path is exercised rather than a shortcut; the only difference from a normal report submission is that the reporter and receiver share an identity. This matches "THERE ARE NO INTERACTIONS OUTSIDE THE PROTOCOL": no ad-hoc case injection or create-case trigger bypass.

ECA Details

Steps

1. [vendor] POST submit-report trigger directed at self (vendor inbox) → Report delivered to Vendor inbox via standard HTTP delivery path
2. [vendor] BT processes inbound report; RM transitions RECEIVED→VALID → Report validated; RM state VALID
3. [vendor] BT engages case; RM transitions VALID→ACCEPTED → VulnerabilityCase created on Vendor/CaseActor; Vendor holds CVDRole.VENDOR + CVDRole.CASE_OWNER; default embargo initialized EM.ACTIVE (EP-04-001)

DEMOMA-25-003 MUST In the VC scenario, the Vendor MUST invite the Coordinator into the case with the invite-actor-to-case trigger.

The Invite/Accept exchange (CM-25) is the correct admission mechanism regardless of role. A trigger makes the Vendor decide and send the invitation itself, so the scenario exercises the real path.

ECA Details

Steps

1. [vendor] POST invite-actor-to-case trigger for Coordinator with OBSERVER role → Invite(VulnerabilityCase preview)[target=Actor] sent to Coordinator inbox
2. [demo_script] Poll Coordinator DataLayer until Invite(VulnerabilityCase preview)[target=Actor] is visible → Invitation record present in Coordinator replica
3. [coordinator] POST accept-case-invite trigger directed to CaseActor → Coordinator becomes a signatory with CVDRole.OBSERVER; CaseActor emits Announce(VulnerabilityCase) to seed Coordinator replica

DEMOMA-25-009 MUST In the VC scenario, the Coordinator's case role MUST be CVDRole.OBSERVER alone, not CVDRole.COORDINATOR.

The Vendor, not the Coordinator, owns the case and drives coordination. Assigning CVDRole.COORDINATOR here would be semantically incorrect.
Extends: DEMOMA-25-003
DEMOMA-25-010 MUST In the VC scenario, the Coordinator MUST accept the invitation with the accept-case-invite trigger.

An OBSERVER that has not joined is inert and receives no case updates (CM-10-004). Accepting through the trigger exercises the joining path of CM-25.
Extends: DEMOMA-25-003
DEMOMA-25-011 MUST In the VC scenario, the Coordinator MUST become an embargo signatory.

The case has an active embargo, so signing is what makes the Coordinator an active participant entitled to case-content announcements as an Observer (CM-10-004, CM-25, CM-26). An OBSERVER that is not a signatory while an embargo is active is inert.
Extends: DEMOMA-25-003
DEMOMA-25-004 MUST In the VC scenario, the Vendor MUST follow the VFD fix-deployment path (vfd → Vfd → VFd → VFD).

VFD obligations attach to CVDRole.VENDOR and CVDRole.DEPLOYER per CM-26. OBSERVER carries no VFD obligations unless the actor also holds VENDOR or DEPLOYER. Driving Coordinator through VFD triggers in this scenario would incorrectly exercise a code path that the OBSERVER role is not supposed to activate.
DEMOMA-25-012 MUST NOT In the VC scenario, the Coordinator, holding only CVDRole.OBSERVER, MUST NOT be driven through VFD steps. It tracks only pxa state updates, the public-awareness transitions that every signatory participant shares.

OBSERVER carries no VFD obligations unless the actor also holds VENDOR or DEPLOYER (CM-26). Driving the Coordinator through VFD triggers would exercise a code path that the OBSERVER role is not supposed to activate.
Extends: DEMOMA-25-004
DEMOMA-25-005 MUST The VC scenario MUST reach a final state in which both the Vendor and the Coordinator are at RM.CLOSED. The scenario verifies LedgerFanout replica convergence of the Coordinator replica against the authoritative Vendor/CaseActor state after each major protocol event.

A participant that is not closed at the end shows that a closure did not reach it. A convergence check after each major event finds the first update that did not reach the Coordinator replica.
DEMOMA-25-013 MUST In the VC scenario, the Vendor MUST reach VFDPxa CS with EM.EXITED.

The Vendor holds the fix path in this scenario. Its final state shows that the fix lifecycle and publication both completed and that the embargo ended.
Extends: DEMOMA-25-005
DEMOMA-25-014 MUST In the VC scenario, the Coordinator MUST reach pxa CS with EM.EXITED, an Observer-only state with no VFD part.

The Coordinator is an Observer with no fix path, so its correct final CS state has no VFD part. A check that expected VFDPxa for the Coordinator would fail on every correct run.
Extends: DEMOMA-25-005
DEMOMA-25-006 MUST The implementation of the VC scenario MUST register it with the scenario registry (DEMOCI-11-001) in the same PR. Its generated .github/demo-scenarios.json entry (DEMOCI-11-004) then runs it as its own CI matrix job.

A scenario that is not registered does not run in CI, so it can break without notice.
Refines: DEMOCI-03-002
Refines: DEMOCI-11-001
See also: DEMOCI-11-004 — descriptive: names the registration the scenario then has
DEMOMA-25-015 MUST The VC implementation MUST ship a dedicated case-ledger invariant test file, test/ci/invariants/test_vc_invariants.py, built on the shared invariant library.

A dedicated file holds the checks that make VC different from the other scenarios. The shared library keeps the universal checks the same as in every other scenario.
DEMOMA-25-016 MUST The VC invariant test MUST assert the semantic-type list of DEMOMA-16-015 and the pxa-only final state of the Coordinator.

The ledger types and the Observer final state make VC different from the other scenarios. Without those checks, a run in which the Coordinator never joined, or ended in a state that has a fix path, could still pass.
Verifies: DEMOMA-16-015

ActorSession — typed demo trigger API

ID Priority Requirement Related
DEMOMA-26-001 MUST NOT Demo scripts under vultron/demo/scenario/ and vultron/demo/exchange/ MUST NOT call post_to_trigger directly.

post_to_trigger accepts a bare string behavior name and an untyped body dict. A misspelled behavior name is a 404 at runtime; a misspelled body key is silently dropped by extra="ignore" request models (TRIG-03-002), producing an undetectable no-op. ActorSession makes both mistakes unrepresentable at the call site. post_to_trigger remains as the private implementation of ActorSession._post and MUST NOT be imported outside the vultron/demo/utils/ package and vultron/demo/actor_session/binding.py.
Derives from: DEMOMA-26-007
DEMOMA-26-007 MUST Demo scripts under vultron/demo/scenario/ and vultron/demo/exchange/ MUST make every trigger endpoint call through a typed ActorSession method.

A typed method fixes the behavior name and the body keys at the call site. Any other path to a trigger endpoint, such as a hand-built URL, brings back the misspelled name or key that a request model with extra="ignore" drops without an error (TRIG-03-002).
Depends on: DEMOMA-26-004
DEMOMA-26-002 MUST ActorSession MUST be a frozen dataclass with the fields client: DataLayerClient, actor: as_Actor, case_id: str &#124; None = None and narrate: bool = True.

The frozen constraint prevents callers from drifting the (client, actor) pairing after construction. Typed fields let mypy catch a wrong argument at the call site.
DEMOMA-26-008 MUST ActorSession.__post_init__ MUST run the container/actor authority check once, at construction, and not on each trigger call.

The check was formerly _assert_client_hosts_actor, run on every trigger call. At construction it makes a mismatched (client, actor) pair unconstructible, rather than a runtime guard that silently passes in unit tests, where neither side is a real absolute URI.
Extends: DEMOMA-26-002
DEMOMA-26-003 MUST ActorSession.with_case(case: as_VulnerabilityCase &#124; str) -> ActorSession MUST return a new frozen ActorSession whose case_id is the case's ID, or the given ID.

A case does not exist when the session is constructed, because the actor must exist before the case does. A with_case copy keeps the session frozen and stops a binding from changing between steps. A trigger names its case by ID, so the session keeps only the ID. A caller that holds only the ID binds it directly and does not build a placeholder case, which could not name the Case Owner.
Extends: DEMOMA-26-002
DEMOMA-26-009 MUST NOT ActorSession.with_case MUST NOT modify the session it is called on.

A session that changed its case in place would change the binding of every step that holds it. A copy keeps each step's binding fixed.
Extends: DEMOMA-26-003
DEMOMA-26-010 MUST A case-scoped ActorSession trigger method MUST raise when self.case_id is None at call time.

A case-scoped trigger with no case would post a request the endpoint cannot act on. Raising at the call site names the missing binding at once.
Extends: DEMOMA-26-003
DEMOMA-26-004 MUST ActorSession MUST expose one typed method per trigger verb that vultron/demo/ calls.

A behavior: str pass-through removes the static check that is the reason ActorSession exists. One typed method per verb keeps the behavior name fixed at the call site.
DEMOMA-26-011 MUST Each ActorSession trigger method MUST accept only the keyword arguments that are meaningful for its verb, with no **kwargs.

A request model with extra="ignore" drops an unknown key without an error. If a method accepts a keyword that its request model does not have, or any keyword at all through **kwargs, a misspelled key gets through without notice.
Extends: DEMOMA-26-004
DEMOMA-26-012 MUST An architecture ratchet test MUST verify that the keyword parameters of each ActorSession method are a subset of its trigger request model's fields, minus actor_id.

A review cannot reliably compare each method with its request model by eye. A ratchet that compares them fails on a keyword that the model does not have, the moment the method gains it.
Verifies: DEMOMA-26-011
DEMOMA-26-005 MUST The PR that lands ActorSession MUST delete vultron/demo/helpers/actions.py, and it leaves no backward-compatibility shim or re-export stub for its functions.

actions.py is a 1:1 wrapper layer over post_to_trigger that ActorSession wholly subsumes. Keeping it alongside ActorSession would leave two competing APIs for the same operations, undoing the consolidation goal.
DEMOMA-26-013 MUST The PR that lands ActorSession MUST migrate every caller of vultron/demo/helpers/actions.py to ActorSession methods.

Deleting actions.py without migrating its callers breaks them, and migrating them in a later PR leaves two competing APIs in the meantime.
Extends: DEMOMA-26-005
DEMOMA-26-006 MUST The PR that removes the last post_to_trigger call site from vultron/demo/ MUST delete the architecture ratchet test test/architecture/test_demo_trigger_client_matches_actor.py.

The test finds the (client, actor_id) mismatch that ActorSession makes impossible to write. When no post_to_trigger call site remains, that mismatch cannot occur, so the test checks nothing.
DEMOMA-26-014 MUST NOT A PR MUST NOT delete test/architecture/test_demo_trigger_client_matches_actor.py while a post_to_trigger call site remains in vultron/demo/.

Until the last call site is gone, the test is the migration's own safety net against new (client, actor_id) mismatches.
Extends: DEMOMA-26-006

RCV-Reject Scenario (Coordinator invites Vendor; Vendor rejects the invitation)

Trigger: Scenario Start — rcv-reject

ID Priority Requirement Related
DEMOMA-27-001 MUST The RCV-reject scenario MUST involve four actor identities, each with its own isolated DataLayer and separate container: Reporter, Coordinator, Vendor and CaseActor. Throughout, the Coordinator holds CVDRole.CASE_OWNER and the CaseActor holds CVDRole.CASE_MANAGER.

The topology is DEMOMA-12's (RCV): the scenario exists to isolate one divergence — the invitation response — so every other variable is held equal.
Refines: DEMOMA-01-001
DEMOMA-27-005 MUST The RCV-reject scenario MUST seed the Vendor as a full actor identity, although the Vendor never becomes an active participant (CM-10-004).

The rejection is a protocol message that the Vendor must author. A placeholder actor could not send Reject(Invite(VulnerabilityCase preview)[target=Actor]), and the point of the scenario is that the rejection travels the wire.
Extends: DEMOMA-27-001
Uses definition from: CM-10-004
DEMOMA-27-002 MUST In the RCV-reject scenario, the Vendor MUST reject the case invitation by sending Reject(Invite(VulnerabilityCase preview)[target=Actor]).

This is the only scenario covering the invitation-layer rejection path, so it is the only place the protocol's "invited but never participating" outcome is exercised end to end.
Extends: DEMOMA-27-001
DEMOMA-27-006 MUST In the RCV-reject scenario, the CaseActor MUST record a reject_invite_actor_to_case ledger entry for the Vendor's rejection.

The ledger entry is the case's record that the invitation was answered. Without it, the case cannot tell a rejected invitation from one still pending.
Extends: DEMOMA-27-002
DEMOMA-27-007 MUST In the RCV-reject scenario, the Vendor's participant record, which the stub Invite created, MUST end at RM.CLOSED.

The stub Invite creates a participant record before the Vendor answers. A record left open after the rejection would leave a participant the protocol no longer expects anything of.
Extends: DEMOMA-27-002
DEMOMA-27-008 MUST NOT In the RCV-reject scenario, the Vendor MUST NOT become active.

The negative half is the load-bearing half. A rejection that still made the Vendor active would satisfy a check that only looked for the ledger entry, while leaving the case in a state the protocol forbids (ADR-0114).
Extends: DEMOMA-27-002
DEMOMA-27-009 MUST NOT In the RCV-reject scenario, the Vendor MUST NOT receive a case ledger replica.

A replica is case content. A rejection that still shipped a replica to the Vendor would give case content to an actor that is not a participant (ADR-0114).
Extends: DEMOMA-27-002
DEMOMA-27-010 MUST NOT In the RCV-reject scenario, the Vendor MUST NOT appear as a recipient of any later case-content fan-out.

The roster keeps the Vendor's closed record, but a closed record grants no entitlement to case content (ADR-0114). A fan-out that still named the Vendor would leak case content past the rejection.
Extends: DEMOMA-27-002
DEMOMA-27-003 MUST The RCV-reject scenario MUST run its phases in this order: report submission, invitation and rejection, replica-sync verification, notes exchange, publication, case closure and ledger dump.

Phase order is the causal order (EDF-06, ADR-0058): the rejection must precede sync verification, because what sync verification asserts is the absence of a Vendor replica, and asserting that before the rejection has been processed would pass vacuously.

ECA Details

Preconditions

- All four containers running (Reporter, Coordinator, Vendor, CaseActor); all actors seeded and cross-registered; no VulnerabilityCase exists for this report; the Coordinator is pre-configured with the dedicated CaseActor container URL (DEMOMA-27-001).

Steps

1. [reporter] report_submission phase — POST submit-report trigger directed at the Coordinator, which validates the report and engages the case → VulnerabilityCase created with the Coordinator as CVDRole.CASE_OWNER and the CaseActor as CVDRole.CASE_MANAGER on its own container (DEMOMA-27-001)
2. [coordinator] invite_vendor_reject phase — Coordinator sends Invite(VulnerabilityCase preview)[target=Actor] to the Vendor with CVDRole.VENDOR → invite_actor_to_case recorded in the case-actor log (DEMOMA-16-011)
3. [vendor] Vendor responds with Reject(Invite(VulnerabilityCase preview)[target=Actor]) rather than Accept(...) → reject_invite_actor_to_case recorded (DEMOMA-27-006); the Vendor's participant record is at RM.CLOSED (DEMOMA-27-007), it never becomes active (DEMOMA-27-008), and it holds no case ledger replica (DEMOMA-27-009)
4. [coordinator] sync_verification phase — verify replica agreement across the participants that exist → Reporter and Coordinator replicas agree with the case-actor log; no Vendor replica is present, which is the assertion the rejection makes checkable (DEMOMA-27-009)
5. [coordinator] notes_exchange phase — participants exchange case notes → add_note_to_case recorded (DEMOMA-16-001)
6. [coordinator] publication phase — the case is published → participants advance to the public-aware CS.pxa states
7. [coordinator] case_closure phase — the Coordinator and Reporter each close the case → every participant at RM.CLOSED, which the universal Invariant 7 check (test_invariant_7_log_terminates_all_rm_closed) asserts for every scenario rather than this group
8. [coordinator] dump_case_ledgers phase → one case-ledger JSONL artifact per participating actor under devlogs/rcv-reject/

Postconditions

- The case is closed with the Reporter and Coordinator as its only participants, and the case-actor log holds exactly one reject_invite_actor_to_case entry and no accept_invite_actor_to_case entry (DEMOMA-16-011, DEMOMA-27-006).

Extends: DEMOMA-27-001
DEMOMA-27-011 MUST In the RCV-reject scenario, the Reporter and Coordinator MUST complete publication and closure without the Vendor.

Closing the case without the Vendor is the scenario's demonstration that a rejected invitation does not block lifecycle completion for the remaining participants.
Extends: DEMOMA-27-003
DEMOMA-27-004 MUST The RCV-reject story MUST start with the same shared opening as RCV (DEMOMA-12-017) and continue from the Vendor's rejection.

The rejection is the only thing this scenario tells differently, so everything before it is one copy of the code shared with RCV and the two recordings are byte-identical up to the Vendor's decision (DEMOCI-11-018). Naming it here keeps this group a whole story: a reader sees where the rejection path begins without reading RCV's group.
Refines: DEMOMA-17-001
Uses definition from: DEMOMA-12-017

RV-CSAF Scenario (a Reporter's CSAF report starts the Vendor's case)

Trigger: Scenario Start — rv-csaf

ID Priority Requirement Related
DEMOMA-28-001 MUST The RV-CSAF scenario MUST involve three actor identities, each with its own isolated DataLayer and separate container: Reporter, Vendor and CaseActor. Throughout, the Vendor holds CVDRole.CASE_OWNER and the CaseActor holds CVDRole.CASE_MANAGER.

The topology is rv's (DEMOMA-06): the scenario exists to show one thing, a case that starts from a CSAF report, so every other variable is held equal to the baseline two-party run.
Refines: DEMOMA-01-001
DEMOMA-28-002 MUST In the RV-CSAF scenario, the Reporter MUST call submit-report with a CSAF 2.1 vulnerability report attached and no report name, summary or embargo end. The Vendor has first published a default embargo longer than the term to the document's disclosure_date.

Stating none of the three leaves each one to the document (CSAF-04-010), so the case's values can only have come from it. The Vendor's longer default gives the document's date an actor default to compete with, so the run shows shortest-wins (EP-04-003) rather than an uncontested proposal.
Refines: CSAF-04-010
DEMOMA-28-003 MUST The RV-CSAF scenario MUST check the canonical case against the CSAF document. Its name is the document.title and its summary the document-level summary note. Its active embargo ends at the disclosure_date, and the Vendor's default is the pending revision.

These are the values a CASE_MANAGER fills from an initial CSAF report (CSAF-03-001, CSAF-03-007). Reading them on the CaseActor's store checks the side that created the case, not a replica that may lag it (DEMOMA-06-004).

ECA Details

Preconditions

- The Reporter, Vendor and CaseActor containers are running, the actors are seeded and cross-registered, and no VulnerabilityCase exists for the report (DEMOMA-28-001).

Steps

1. [vendor] The Vendor publishes its default embargo policy on its own profile. → The Vendor's profile carries an EmbargoPolicy longer than the document's term (DEMOMA-28-002).
2. [reporter] The Reporter calls submit-report with the CSAF document attached and no report name, summary or proposed embargo end; the Vendor validates the report and engages the case. → The Offer's report is named from the document's title and its proposedEmbargo ends at the document's disclosure_date (CSAF-04-010); the CaseActor creates the case with the Vendor as CVDRole.CASE_OWNER (DEMOMA-28-001).
3. [reporter] The scenario reads the canonical case on the CaseActor's container. → The case's name, summary and active embargo end are the document's, and the Vendor's default is the one pending revision (DEMOMA-28-003).
4. [vendor] The note thread, the Vendor's fix, the publication and the closure follow as in rv. → Every participant at RM.CLOSED, which the universal Invariant 7 check (test_invariant_7_log_terminates_all_rm_closed) asserts for every scenario rather than this group.

Postconditions

- The case is closed, and its name, summary and first embargo came from the Reporter's CSAF report (DEMOMA-28-003).

Refines: CSAF-03-001
Refines: CSAF-03-007
DEMOMA-28-004 MUST The RV-CSAF scenario's CSAF document MUST be a document this project wrote that is schema-valid against the pinned CSAF 2.1 revision.

The suite never reads the CSAF Technical Committee's test documents (CSAF-05-004), and the submit-report trigger refuses a document that is not schema-valid (CSAF-04-009), so an invalid fixture would stop the scenario at its first act.
Refines: CSAF-04-009
DEMOMA-28-005 MUST After the case starts, the RV-CSAF story MUST tell rv's note thread, fix, publication and closure with rv's own fragments.

Only the opening differs from rv, so what follows the case's start is one copy of the code (DEMOMA-17-001), and a fix to rv's ending reaches this scenario too.
Refines: DEMOMA-17-001

Notes Frontmatter

Requirements for YAML frontmatter in notes files, covering the required schema, a Pydantic-based loader, validation enforcement, migration requirements, what a note is for and how it is written, and the report that flags delivered plan notes.

File ID: NF

Frontmatter Schema

ID Priority Requirement Related
NF-01-015 MUST The notes loader MUST reject a generated note that lacks the NF-01-011 marker, with an error that names the file per NF-03-006.

The check stops the loader from treating a generated note as a hand-written note. An error that names the file tells the editor which note to fix.
Verifies: NF-01-011
Refines: NF-03-006

Pydantic Schema Module

ID Priority Requirement Related
NF-02-001 MUST The vultron/metadata/notes/ subpackage MUST define a Pydantic model (NotesFrontmatter) that validates the frontmatter schema described in NF-01.

A Pydantic model gives one executable definition of the schema. Thus the loader, the pre-commit hook and the corpus test all apply the same rules.
NF-02-002 MUST NotesFrontmatter MUST use a StrEnum for the status field vocabulary (NoteStatus).

A StrEnum makes the status vocabulary one type, which validation and code both use. Thus validation rejects an unknown status, and the status is not stored.
NF-02-003 MUST Shared base vocabulary (e.g., common StrEnum base classes or type aliases) MUST live in vultron/metadata/base.py and be importable by both metadata/notes/ and the future metadata/specs/ subpackage.

The notes, specs and history tooling use the same vocabulary types. One shared base module defines those types one time, so that each subpackage does not keep its own copy.
NF-02-004 MUST NOT The vultron/metadata/ package MUST NOT import from vultron/core/, vultron/wire/, or vultron/adapters/; it is a standalone tooling layer with no dependency on application code.

The metadata tooling runs in hooks and CI. If it imports application code, it becomes slower, and protocol changes can break it. If it stays independent, it can validate documents when application code is broken.

Loader

ID Priority Requirement Related
NF-03-001 MUST The vultron/metadata/notes/ subpackage MUST provide a loader that discovers and parses all notes/*.md files relative to the repository root.

Validation and selection both need all of the notes. The loader finds each file relative to the repository root, so each caller gets the same set from any location.
NF-03-002 MUST The loader MUST skip notes/README.md.

notes/README.md is the directory index, not a note, and it has no note frontmatter. If the loader parses it as a note, it fails the validation that all other files must pass.
NF-03-003 MUST The loader MUST parse each file's YAML frontmatter block and validate it against NotesFrontmatter, raising a ValueError (or equivalent) on schema violations.

A note that does not agree with the schema must stop the hook and the test. It must not load without an error. A ValueError gives callers one exception type to report.
NF-03-004 MUST The loader MUST return a registry mapping file path to validated NotesFrontmatter instance.

Callers find notes by path. A registry with the path as its key gives them validated frontmatter, and they do not parse each file again.
NF-03-005 SHOULD The loader SHOULD resolve the repository root by searching upward from the current working directory for a pyproject.toml file, so it works correctly regardless of where it is called from.

The loader runs from hooks, from tests and from the shell, each with a different working directory. The loader finds the root from pyproject.toml, so it loads the same notes from each of them.
NF-03-006 MUST The ValueError that NF-03-003 requires MUST name the notes file at fault, per MS-17-001. This applies to a frontmatter parse failure and to a NotesFrontmatter validation failure.

The loader reads all files in notes/, so an error that names only a field path does not identify the incorrect file.
Refines: MS-17-001
Extends: NF-03-003
NF-03-007 MUST The notes loader MUST obtain the file attribution of its errors from the shared helper that MS-17-003 names.

One helper formats the errors of every metadata loader in the same way. A private copy in the notes loader could drift from that format.
Refines: MS-17-003
NF-03-008 MUST NOT The notes loader MUST NOT let a malformed frontmatter block surface as a raw parser traceback.

A frontmatter block that the parser cannot read causes a YAML error, which is not a ValueError. Without this rule, that error does not obey the contract of NF-03-003, and the pre-commit hook shows a traceback.
Extends: NF-03-003

Validation Enforcement

ID Priority Requirement Related
NF-04-001 MUST A pytest test MUST load all notes/*.md files via the loader and assert that every file parses without validation errors.

The pre-commit hook runs only when a note file is staged. Thus a change to the loader or schema can break existing notes, and the hook does not run. A test in the suite runs on each change, so all notes are known to parse at each commit.
NF-04-002 MUST A pre-commit hook MUST validate the frontmatter of any changed notes/*.md file before the commit is accepted.

A check at commit time finds a frontmatter error while the author has the file open. Without it, CI or the next tool that reads the file finds the error later.

Future: Registry and Query Tool

ID Priority Requirement Related
NF-07-001 MAY A query/dump tool MAY be built (in a later task) that accepts a topic keyword and returns all notes (and eventually specs) whose frontmatter indicates relevance to that topic.

A topic lookup on frontmatter lets an agent find the notes for a topic without a read of each note. The requirement is optional, because a person can already use the frontmatter to select notes by hand.
NF-07-002 MAY The notes/README.md index MAY be generated from the notes registry in a later task, replacing the manually-maintained summaries with content derived from description frontmatter fields.

A hand-maintained index becomes different from the notes that it summarizes. An index generated from the description fields stays the same as the notes, but somebody must build the generator.

Plan Retirement Report

ID Priority Requirement Related
NF-09-001 MUST The notes-tracks command MUST list every plan note whose tracked issues (NF-01-010) are all closed, and every plan note that tracks a number that is not a known issue.

Plan notes retire when their work lands (NF-08-001), but nothing tells a maintainer when that occurs. The command lists the plans whose tracked issues are all closed, or whose references are unknown, so that the next sweep includes them.
Uses definition from: NF-01-010
NF-09-002 MUST NOT The notes-tracks command MUST NOT archive, edit, or fail on a flagged note; a flagged note is an agenda item for the next notes sweep, decided by a person or the sweep's interview. The command exits non-zero only when the issue lookup itself fails.

A closed issue is evidence, not proof, that a plan is delivered; follow-up bugs and re-scoped work often keep a plan relevant past its first issue.
Extends: NF-09-001

Object ID

Requirements for the format and handling of object identifiers throughout the Vultron system. Establishes full-URI IDs as the canonical form for all ActivityStreams objects and DataLayer records.

File ID: OID

ID Format

ID Priority Requirement Related
OID-01-003 MUST The canonical base URI for locally created objects MUST be configurable via an environment variable (VULTRON_BASE_URL or equivalent)

How a deployment sets the base of the IDs it mints is an operating choice of this codebase; a peer sees only the resulting IDs. Only this codebase must obey it, so it is project (ADR-0134).
OID-01-004 MUST This codebase MUST mint every new object ID through one helper that the core and wire layers share.

If each layer built IDs its own way, objects could get IDs in different forms (bare UUID, urn:uuid:, base-URL HTTPS), and lookups by full URI would miss some of them (OID-02-004). One helper keeps every minted ID in one form. The wire layer may import vultron/core/models (ARCH-22-001), so a helper there can serve both layers.
OID-01-005 MUST Actor IDs MUST be normalized to full URI form at the point of first establishment — actor creation, seed data loading, or session initialization

When this codebase normalizes an actor ID is an internal choice. What a peer observes, an id that is a full IRI, is ActivityStreams' rule (MV-05-001). Only this codebase must obey the normalization point, so it is project (ADR-0134).
OID-01-006 MUST A receiver MUST normalise each actor id that it extracts from a received activity to act on, by stripping a trailing slash. It does so at the point of extraction. To act on an id is to look it up, compare it with a stored id, or store it as a key.

The values the receiver works with must have one spelling, or exact lookups miss records written in the other: a peer that spells its id with a trailing slash would not match its own CASE_OWNER records stored under the canonical spelling. Normalising where the value is extracted, not where it is compared, lets core trust one spelling (ADR-0032).
OID-01-008 MUST A receiver MUST store and ledger a received activity as received, with the actor ids spelled as the sender wrote them.

File the letter as received; normalise only what you copy out of it (OID-01-006). The stored activity and the ledger postmark are evidence of what the sender wrote (ADR-0107), so they keep the sender's spelling.
OID-01-007 MUST The wire extractor MUST normalise a received activity's sender id before it builds the received event.

The sender id reaches every received use case, so normalising it once at the edge replaces a trailing-slash-tolerant comparison at each of its uses. An id the sender wrote elsewhere in the activity keeps its spelling until it is extracted (OID-01-006), so comparing it with the sender id still needs same_actor_id (CLP-10-021). The normalising function must be importable from vultron/wire/ and vultron/core/models/, which may not import vultron/core/predicates/ (ARCH-22-001).
Refines: OID-01-006
OID-01-009 MUST A received event MUST refuse, at construction, a sender id that ends in a trailing slash.

Refusing an unnormalised id at construction makes a path that skips the extractor (a trigger, a test fixture) fail where it builds the event, instead of storing the other spelling (ARCH-10-001).
Refines: ARCH-10-001
OID-01-011 MUST The object id minter MUST draw every new id from the installed id source.

A run that needs repeatable ids then replaces one id source for a block, through one scoped install, instead of patching uuid.uuid4 for the whole process. The system id source is the default because create_app() installs nothing (ARCH-16-001).
Refines: OID-01-004
OID-01-012 MUST NOT Code under vultron/ other than the system id source MUST NOT draw a random UUID for an object id or replace the uuid module's draw.

A replacement of uuid.uuid4 reaches every caller of it, py_trees included, so a reproducible run's ids would depend on how many tree nodes it built. A run that needs repeatable ids therefore installs its source through the scoped install (OID-01-011).
Refines: OID-01-004

DataLayer Handling

ID Priority Requirement Related
OID-02-001 MUST The DataLayer MUST store and retrieve objects using their full-URI as_id as the primary key

The full URI is the object's identity on the wire and across deployments (OID-01-001, OID-01-002). A shortened key could collide between objects from different deployments and would need a translation at every lookup of a received id.
OID-02-002 MUST object_to_record() MUST preserve the full-URI as_id when serializing objects to the DataLayer

A record that drops or shortens the id cannot be found again by the id peers use, and objects from different deployments that share a UUID could overwrite each other.
OID-02-003 MUST record_to_object() MUST reconstruct objects using the full-URI as_id stored in the record

The id on a rebuilt object is what core compares and what outbound activities carry. Rebuilding it from anything other than the stored full URI could give the object an identity different from the one its peers know.
OID-02-004 MUST NOT A DataLayer lookup MUST NOT accept a bare UUID as a lookup key.

Accepting a bare UUID as a key would give one object two keys and let a UUID match an object from another deployment with the same UUID. Refusing it keeps one spelling for each id in the store.

Blackboard Key Handling

ID Priority Requirement Related
OID-03-001 MUST NOT Behavior Tree blackboard keys derived from object IDs MUST NOT use the raw full URI as the key

A full URI contains /, which py_trees reads as a blackboard namespace separator, so a raw URI used as a key is split into nested namespaces instead of naming one entry. Deriving the key from the id's final path segment avoids the misparse.
Refines: BTND-03-005

Migration Requirements

ID Priority Requirement Related
OID-04-002 MUST Any migration of existing bare-UUID records MUST be accompanied by a migration script or documented manual steps

A change in id form leaves existing records under keys that full-URI lookups do not find (OID-02-004). Without a script or written steps, an operator upgrading a deployment cannot bring stored records forward, and those records drop out of the system without an error.

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

Outbox Structure

ID Priority Requirement Related
OX-01-001 MUST Each actor MUST have an outbox collection

ActivityPub gives each actor an outbox, and Vultron delivers every outbound activity from it. The outbox holds an activity until its delivery succeeds or fails for good. Thus every actor that sends activities must have one.
OX-01-002 MUST Outbox MUST preserve insertion order (FIFO)

Recipients apply some activities in order, for example ledger entries (OX-01-005). If the outbox does not keep the order in which the actor queued its activities, delivery cannot keep that order either.
OX-01-003 MUST Activities added to outbox MUST be persisted to DataLayer immediately

An activity that is queued only in memory is lost when the process stops, and its recipients never receive it. When the outbox entry is in the DataLayer at once, a restart can continue delivery from the stored queue.
OX-01-004 MUST At most one drain of an actor's outbox MUST run at a time.

The background task of each inbound activity and the OutboxMonitor can each start a drain of the same outbox. Each concurrent drain pops the next row and waits for its POST. Thus rows complete delivery in an order that has no relation to their enqueue order. One drain at a time keeps the FIFO order of OX-01-002 at the recipient. See ADR-0112.
Implements: OX-01-002
OX-01-007 MUST A drain request that arrives while another drain of the same outbox runs MUST wait for that drain or let it do the work. It does not pop rows from the queue at the same time.

A second drain that pops rows beside the first one breaks the one-drain rule of OX-01-004. A request that fails instead would leave a newly queued row without a drain. When the request waits, or the running drain takes the new rows, every row is sent and the order holds.
Implements: OX-01-004
OX-01-005 MUST The outbox handler MUST finish the delivery attempt of an earlier-queued activity to a recipient before it attempts a later-queued activity to that recipient.

A ledger fan-out is one Add(CaseLedgerEntry) row per participant, and a replica that receives entry N+1 before entry N buffers a forward gap and sends a Reject(CaseLedgerEntry) (SYNC-14-002), which the CASE_MANAGER answers with a full-suffix replay into the same outbox. Per-recipient order at delivery is the property the ledger transport actually needs; order across recipients is not. See ADR-0112 (docs/adr/0112-per-recipient-ordered-outbox-delivery.md).
Refines: OX-01-002
Implements: SYNC-19-007
OX-01-006 MUST An actor's outbox MUST NOT have more than one delivery in flight to the same recipient at a time.

One in-flight delivery per (actor, recipient) is how OX-01-005 is enforced without falling back to a single serial drain, in which one slow or unreachable recipient (a 30 s POST timeout, SYNC-05-004) would hold up every other recipient's rows. See ADR-0112 (docs/adr/0112-per-recipient-ordered-outbox-delivery.md).
Implements: OX-01-005
OX-01-008 MAY An actor's outbox MAY run deliveries to distinct recipients at the same time.

The order rule of OX-01-005 holds for each recipient, not across recipients. When deliveries to distinct recipients run at the same time, one slow or unreachable recipient does not hold up the rows of every other recipient.

Outbox Population

ID Priority Requirement Related
OX-02-001 MUST Handlers that generate response activities MUST add them to the actor's outbox

The outbox is the only path by which an activity leaves an actor (OX-12-001). A response that a handler does not queue there never reaches its recipient. The outbox also cannot retry it or record a failed delivery.

Outbox Delivery

ID Priority Requirement Related
OX-03-002 MUST NOT The outbox MUST NOT deliver an entry before the act that queued it has committed.

An outbound activity reports the result of the act that queued it. If delivery starts before that act commits, a recipient can receive an activity for an act that then fails and keeps none of its writes, so the recipient acts on a change the sender never made. The drain wakes as soon as an activity is queued (OX-09-001), so only the commit can order the two.
OX-03-003 MUST NOT Delivery MUST NOT block inbox HTTP response

The sender's POST waits for the inbox response. If that response waited for the deliveries of the receiving actor, one slow or unreachable recipient would slow every sender whose delivery waits behind it, and their POST requests could time out. Thus the inbox answers 202 first (IE-07-002) and delivers later.

Local Delivery

ID Priority Requirement Related
OX-04-001 MUST For actors on the same server, delivery MUST use HTTP POST to the recipient actor's inbox endpoint ({actor}/inbox/) in the same manner as remote delivery, per OX-12-001. Direct DataLayer writes that bypass the HTTP path are prohibited.

A co-located actor is a separate actor, and it knows only the activities that arrive at its inbox (AKM-01). A direct DataLayer write skips the inbox checks. It also makes local delivery behave differently from remote delivery, and that hides delivery defects (OX-12-005).
Refines: OX-12-001

Federation Delivery

ID Priority Requirement Related
OX-05-001 MAY For remote actors, the system MAY deliver via HTTP POST to the remote actor's inbox URL

A remote actor can receive an activity only at its inbox URL, and HTTP POST is the ActivityPub way to deliver there. The rule is MAY because federation with other servers is a production capability that the prototype does not need.
OX-05-002 SHOULD Remote delivery failures SHOULD be logged at WARNING level and retried

A remote server can be unreachable for a short time. A retry delivers the activity when the server is available again. The WARNING tells the operator that delivery to that server has a problem. A failed delivery with no log and no retry is lost with no trace.

Delivery Idempotency

ID Priority Requirement Related
OX-06-001 MUST Outbox delivery MUST be idempotent

A delivery can occur more than once. The outbox retries after a failure, and a retry can rebuild an activity that was already sent. Idempotent delivery keeps a repeat from changing the state of the recipient a second time. The receiver drops an activity whose id it already holds (ID-02-001).
Depends on: ID-02-001
OX-06-002 MUST An actor's outbox MUST hold at most one pending entry per activity id. When it is asked to queue an activity whose id is already pending, it adds no entry.

A retry after a partial failure must not send an act twice. When the retry rebuilds the activity under its first id (ID-04-004), the outbox alone can tell it is already on its way, whatever the order of commit and send (ADR-0119). The check is in the queue operation so no caller can omit it. An emitting tree whose retry rebuilds its activity under the earlier id thus sends that activity once.
Implements: OX-06-001
OX-06-003 MUST The outbox queue operation MUST report to its caller whether it added an entry.

A caller that rebuilds an activity on a retry needs to know if the activity is new or already on its way. With the answer, the caller can log the repeat and skip work that only a new entry needs.
Extends: OX-06-002
OX-06-004 MUST When an actor's outbox is asked to queue an id that is no longer pending, it MUST queue the activity again under the same id.

An id that left the queue was delivered or dead-lettered. A later resend of the same act must still go out. The receiver drops a copy it already holds by id (ID-02-001), as for a re-sent response (CP-05-006).
Extends: OX-06-002

Outbound Body Sealing and Relay

ID Priority Requirement Related
OX-07-001 MUST The outbox handler MUST deliver each sealed body exactly as it was sealed, with no field changed. To dehydrate, expand, hydrate, re-type or re-serialise a field is to change it.

The activity record cannot serve as the delivery body. Persistence stores reference fields as ids, and a read-back fills them from what the store holds at that time. Thus a re-read is a reconstruction, and it can differ from the body that the ledger records as payloadSnapshot (VM-08-003). For example, the case stub in an Invite can reach the invitee as a bare URI. The factory sets the shape of each reference field, so the handler sends the sealed body as it is. See ADR-0074.
Implements: VM-08-003
Depends on: OX-07-003
OX-07-003 MUST Every adapter that persists an outbound activity for its actor's outbox MUST seal the activity's body in that actor's store when it persists the activity. The sealed body is the factory object's own JSON dump.

The outbox can relay only a body that exists. When the adapter seals the body at the moment it persists the activity, the body is the one the factory built, before any store read can change a reference field. See ADR-0074.
OX-07-004 MUST NOT The outbox handler MUST NOT read the activity record back to build the delivery payload.

Persistence stores reference fields as ids. A read-back fills them from what the store holds at that time, so it can differ from the sealed body that the ledger records. See ADR-0074.
Extends: OX-07-001
OX-07-005 MUST When a queued id has no sealed body, the outbox handler MUST drop the id with an ERROR log and not deliver a reconstruction.

A queued id with no sealed body is a defect in the adapter that queued it. A reconstruction would hide that defect and send a body the ledger never recorded. The ERROR log shows the operator the defect.
Extends: OX-07-001
OX-07-002 MUST NOT The object field of an outbound activity MUST NOT be dehydrated to a reference at any stage — construction, persistence of the sealed body, or delivery. A sealed body whose object is a bare URI or as_Link on an initiating activity is a factory defect that the handler refuses (AKM-03-002), never repairs.

A recipient needs the full object to act on an initiating activity. A bare URI makes it fetch the object from the sender, and the fetched copy can differ from the object at send time. The factory must put the object inline. If the handler repaired the reference, it would hide the factory defect.
Refines: AKM-03-001
See also: AKM-03-002 — context for the reader

Outbox Addressing

ID Priority Requirement Related
OX-08-001 MUST Every activity posted to an actor's outbox MUST have a non-empty to: field

Vultron exchanges are direct messages; there are no public or broadcast activities in the protocol
OX-08-002 MUST The to: field on outbound activities MUST be a list containing at least one URI string

The outbox handler reads to: to find the recipients. A list of URI strings is the one shape that it reads. A list with no entry names no recipient, so the activity cannot go anywhere.
OX-08-003 MUST handle_outbox_item MUST raise VultronOutboxToFieldMissingError when it detects a missing or empty to: field

An activity with no recipient cannot be delivered, and a silent skip hides the factory defect that made it. A specific error lets the outbox handler move the activity to the dead-letter store at once (OX-13-013). It also lets tests check for the defect.
OX-08-004 SHOULD If an outbound activity carries non-empty cc:, bto:, or bcc: fields, the outbox handler SHOULD log a WARNING. There is no exemption.

Vultron direct messages name every recipient in to: (OX-08-001). The cc:, bto: and bcc: fields have no handler semantics (HP-10-001), so a value there is most likely a factory defect. An emitting tree commits its own ledger entry (CLP-10-071, CLP-10-031), so no outbound activity has a reason to copy its own sender. See ADR-0109.

Outbox Monitor Efficiency

ID Priority Requirement Related
OX-09-001 SHOULD The outbox monitor SHOULD use event-driven wakeup so that it drains actor outboxes immediately when an activity is enqueued, rather than waiting for the next fixed polling interval

Reduces median delivery latency from up to poll_interval to near-zero at no extra CPU cost
OX-09-002 MUST Even when event-driven wakeup is enabled, the outbox monitor MUST retain a safety-net polling interval so that outbox items are eventually delivered even if an enqueue notification is missed

An enqueue notification can be lost, for example when the callback fails. Without a poll, a queued activity then waits until the next enqueue for the same actor, which may not come. The poll limits that wait to one poll interval.
OX-09-003 SHOULD The enqueue notification mechanism SHOULD be injected into the DataLayer adapter as a callback so that the DataLayer does not import from the monitor layer

Preserves the hexagonal architecture boundary between driven adapters
OX-09-004 SHOULD The outbox monitor SHOULD log the total number of pending outbox items across all actors at DEBUG level on each drain pass

The pending count shows an operator whether the outboxes drain or grow. At DEBUG level it does not add noise to normal operation, and it is available when the operator looks for a delivery problem.
OX-09-005 SHOULD If any single actor's outbox depth exceeds a configurable threshold, the outbox monitor SHOULD emit a WARNING-level log entry identifying the actor and depth

A deep outbox shows that delivery to some recipient fails or is slow. The WARNING names the actor, so the operator can find the problem before the queue grows more. A configurable threshold lets each deployment set its own normal load.

Signed Remote Delivery

ID Priority Requirement Related
OX-10-001 SHOULD For remote actor delivery, the outgoing HTTP POST SHOULD be signed using HTTP Message Signatures (RFC 9421) with the sending actor's private key

Production federation sends activities to peers that the sender does not control, and mainstream ActivityPub servers authenticate the delivering server by its HTTP signature. The activity's own proof already shows its author (SIG-01-001); the HTTP signature adds who delivered it. RFC 9421 is the standard way to sign an HTTP message. ADR-0164 builds the content proof first, from seeded keys; this transport signature comes later, with production keys (#1184). It is deferred, not dropped.
OX-10-002 MUST Each actor MUST have its own signing key pair, which no other actor shares.

If two actors share a key, a signature cannot tell them apart. One actor can then sign activities as the other. Also, one leaked key exposes every actor that uses it.
Extends: OX-10-001
OX-10-003 MUST NOT The signed delivery adapter MUST NOT construct or inspect ActivityStreams objects. It is transport-only: the payload is serialized before it reaches the adapter.

Preserves the hexagonal layer boundary
Extends: OX-10-001
OX-10-004 MUST Until signed delivery is implemented, the production HTTP delivery adapter MUST raise NotImplementedError if instantiated, so that callers receive an explicit signal rather than a silent no-op.

A delivery adapter that does nothing loses every activity with no error. A NotImplementedError at once tells the caller that signed delivery does not exist yet. Thus nobody can use the stub as a working transport by mistake.

Shared-Inbox Fan-Out

ID Priority Requirement Related
OX-11-001 MAY The system MAY expose a shared inbox endpoint that accepts activities addressed to multiple local actors in a single HTTP request

Shared-inbox delivery sends one POST for many local recipients, not one POST for each. That decreases network load for cases with many participants on one server. The rule is MAY because each per-actor inbox already delivers correctly, so the shared inbox is only an optimization.
OX-11-002 MUST If a shared inbox is implemented, it MUST validate the HTTP Signature on the inbound request before any fan-out processing

A shared inbox delivers one request to many actors. If it starts the fan-out before it checks the signature, one false request reaches every addressed actor. When the check comes first, a false request reaches none of them. The check adds to, and does not replace, each addressed actor's verification of the activity's own proof (SIG-03-001, ADR-0164).
Extends: OX-11-001
OX-11-003 MUST If a shared inbox is implemented, it MUST enqueue one per-actor inbox delivery for each addressed local actor identified in the activity to/cc fields

Each actor processes and stores its activities separately. Thus each addressed local actor must receive its own inbox delivery, as if the sender had posted to it directly. The shared inbox then changes only the transport and not the result.
Extends: OX-11-001
OX-11-004 MUST Until shared-inbox is implemented, adapters/driving/shared_inbox.py MUST raise NotImplementedError if instantiated, so that callers receive an explicit signal rather than a silent no-op

A shared inbox that does nothing loses every activity with no error. A NotImplementedError at once tells the caller that the shared inbox does not exist yet. Thus nobody can use the stub as a working endpoint by mistake.

Uniform HTTP Delivery

ID Priority Requirement Related
OX-12-001 MUST All inter-actor activity delivery MUST occur over the REST inbox/outbox HTTP API (HTTP POST to {actor}/inbox/).

Each actor knows only the activities that reach its inbox (AKM-01). With one delivery path for every actor, the same checks apply to every activity. A delivery defect then shows in local tests as it does between servers. See ADR-0042.
OX-12-005 MUST Delivery to a co-located actor MUST use the same HTTP path as delivery to a remote actor.

Uniform delivery exposes inter-actor delivery bugs that in-process shortcuts would mask, giving accurate confidence in demos and production. See ADR-0042.
Refines: OX-12-001
OX-12-006 MUST NOT There MUST NOT be an in-process delivery shortcut that bypasses HTTP for same-server recipients.

An in-process shortcut makes co-located delivery behave differently from remote delivery, masking bugs and giving false confidence. See ADR-0042.
Refines: OX-12-001
OX-12-002 MUST The default production ActivityEmitter MUST be the HTTP delivery adapter.

A deployment uses the default emitter when nobody configures a different one. If the default is not the HTTP delivery adapter, a deployment can send activities on a path that is not the one that the protocol uses (OX-12-001).
OX-12-003 MUST Application code MUST NOT construct httpx.ASGITransport directly. The sole exception is FastAPI's TestClient, which uses ASGITransport internally to drive a single application's own endpoints and is not an inter-actor delivery mechanism.

An httpx.ASGITransport calls an application in-process and does not use the network. Application code that builds one makes an in-process delivery shortcut, which OX-12-006 prohibits. FastAPI's TestClient is the exception because it tests the endpoints of one application and does not deliver between actors.
OX-12-009 MUST When the sender's held profile of the recipient names an inbox, delivery MUST POST to that inbox.

An actor's profile states where its inbox is, and a peer on another node need not follow this codebase's URL layout (ADR-0159).
Supersedes: OX-12-001
OX-12-010 MUST When the sender holds no inbox for the recipient, delivery MUST POST to the address {actor}/inbox/ derived from the recipient's URI.

The derived address is a reasonable guess for a peer known only by URI (AKM-05-001). It is used only when nothing better is known (AKM-02-006, ADR-0159).
Refines: OX-12-001

Delivery Terminal State

ID Priority Requirement Related
OX-13-001 MUST Each outbox queue entry MUST track a total attempt count that is persisted across drain passes and incremented on every delivery failure, so that the count survives outbox_handler invocations and reflects the activity's cumulative delivery history.

A count that resets at each drain pass lets an undeliverable activity retry forever. The count must persist and increase with each failure, so that the total budget (OX-13-002) can stop the retries.
OX-13-002 MUST The maximum total delivery attempts MUST be configurable.

The correct number of attempts depends on the deployment: how long a recipient can be unavailable, and how much retry traffic is acceptable. A configurable limit lets each deployment set that balance without a code change.
OX-13-007 MUST The maximum total delivery attempts MUST have a documented default value.

A documented default makes the system's reliability envelope observable and predictable without requiring explicit per-deployment configuration.
Extends: OX-13-002
OX-13-008 MUST When an activity exhausts its total attempt budget, it MUST be moved to a dead-letter store.

Moving exhausted activities to a dead-letter store preserves them for operator inspection and provides an observable signal for the terminal failure state.
Uses definition from: OX-13-002
OX-13-009 MUST NOT When an activity exhausts its total attempt budget, it MUST NOT be requeued.

Requeuing an exhausted activity restarts the attempt counter, defeating the total-attempt bound and allowing indefinite retries.
Uses definition from: OX-13-002
OX-13-003 MUST On activity exhaustion, the system MUST log at ERROR level, including the activity ID, the recipient(s) that could not be reached, and the total number of attempts made, so that the operator has a visible signal of the terminal failure.

A dead-lettered activity means that a recipient did not receive an event. The ERROR log is the signal to the operator. The activity id, the unreached recipients and the attempt count let the operator find the activity and decide what to do.
Uses definition from: OX-13-002
OX-13-004 MUST Dead-letter entries MUST be readable from the DataLayer so that operators can inspect exhausted activities without access to application logs.

Logs can rotate, and an operator can have no access to them. Entries in the dead-letter store stay in the DataLayer, so an operator or a tool can list and inspect the exhausted activities.
OX-13-005 MUST The HTTP delivery adapter MUST treat a 4xx response from a recipient inbox as a terminal delivery failure that uses no inner retry slot. Only HTTP 5xx responses, connection errors and timeouts are retryable.

A 4xx response is a deterministic refusal, for example 422 for a body that fails validation. The same body gets the same response each time. A retry uses the retry budget and adds load on the recipient, but it does not deliver the activity. See ADR-0066.
OX-13-006 MUST NOT A single failing activity in an actor's outbox MUST NOT abort delivery of other activities in the same drain pass.

A drain pass delivers many activities, and some of them are ledger entries that participants wait for. If one failing activity stops the pass, the healthy activities behind it wait, and participants can reach a timeout. Thus the failure of an activity must stay with that activity. See ADR-0066.
OX-13-010 MUST Each activity's per-pass error count MUST be tracked independently.

Independent per-activity tracking prevents a single bad activity from consuming the shared cap and blocking delivery of healthy activities in the same pass.
Implements: OX-13-006
OX-13-011 MUST Hitting the per-pass cap for one activity MUST skip that activity for the current pass (deferring it to the next drain) without breaking the drain loop.

Skipping rather than aborting keeps the drain loop running so that subsequent activities in the same pass are delivered on schedule.
Implements: OX-13-006
OX-13-012 MUST When the outbox handler re-queues a failed activity, it MUST re-queue every later-queued activity that shares a recipient with it behind it, in enqueue order. Activities that share no recipient with the failed one are unaffected.

If a failed activity goes to the tail of one FIFO, later rows go before it. One transient failure on ledger entry N then delivers entry N+1 first, and each recipient sees a forward gap (SYNC-14) that the sender caused. When only the rows that share a recipient wait behind the failed row, each recipient keeps its order (OX-01-005), and other recipients do not wait (OX-01-006). See ADR-0112.
Refines: OX-01-005
OX-13-014 MUST NOT In a drain pass where a delivery fails, the outbox handler MUST NOT attempt a later-queued activity to the same recipient before the failed one.

A later row that goes out before the failed row reaches its recipient out of order. For ledger entries, the recipient then sees a forward gap (SYNC-14) that the sender caused. See ADR-0112.
Refines: OX-01-005
OX-13-013 MUST The outbox refuses a sealed body before any delivery attempt when its to: names no recipient (OX-08-003). It also refuses one whose object is not inline (OX-07-002). On that first refusal, the outbox handler MUST move the activity to the dead-letter store with reason undeliverable_body. The activity gets no retry.

The sealed body does not change (VM-08-003), so every retry is refused for the same reason. Retries spend the full attempt budget on backoff delay, and they show a deterministic defect as a transient failure. This is the local counterpart of the 4xx rule (OX-13-005).
Extends: OX-13-008
Extends: OX-08-003
Extends: OX-07-002

Participant Case Replica

Requirements for how each Vultron Actor maintains and manages its local copy (replica) of a VulnerabilityCase. Covers replica identity, bootstrap, update authority, case-context message routing, reporter case discovery, and unknown-context handling.

File ID: PCR

Unknown Case Context Handling

ID Priority Requirement Related
PCR-06-004 MUST This codebase MUST hold the pending-activity queue for unknown case contexts in the receiving actor's own DataLayer, keyed by case ID.

Two Actors can run on one host. Each Actor has its own store (ADR-0073), so a queue held there scopes the replay after one Actor's replica is seeded to that Actor. The store gives the actor scope, so the key needs only the case ID. A shared queue could apply an activity to another Actor's case state, which PCR-01-005 forbids.
Implements: PCR-06-002

Outbound Participant Message Routing

ID Priority Requirement Related
PCR-08-004 MUST NOT Demo scenarios and external clients MUST NOT start the CaseLedgerEntry commit and its broadcast directly. The one exception is the prototype-only POST /actors/{actor_id}/demo/sync-log-entry endpoint (TRIG-09, TRIG-10-004). Replication tests use it to place a known entry, and no demo scenario calls it.

The ledger records what the CASE_MANAGER processed. An entry that a script or client creates directly records no processed activity, skips the CASE_MANAGER's checks, and lets a demo pass when the protocol path it shows does not work.
See also: TRIG-10-004 — context for the reader
PCR-08-006 MUST Unit and integration tests MUST verify that a participant's outbound activity is addressed only to the CASE_MANAGER, and that no direct peer-to-peer delivery is attempted.

Routing every message through the CASE_MANAGER (PCR-08-001) fails without an error when a sender adds one more recipient: the message still arrives, but at a peer as well. Only a test that checks the recipient list finds that.
PCR-08-015 MUST NOT A received-side use case MUST NOT execute a Behavior Tree with actor_id set to any actor other than the one whose DataLayer is active for that use case invocation.

A store belongs to one actor (ADR-0073). A tree that runs as a different actor writes records into this store under that actor's identity, and it emits activities that claim to come from an actor that did not send them (PCR-08-010).
Implements: PCR-08-010
PCR-08-011 MUST An emit node in a case-scoped trigger BT MUST resolve the CASE_MANAGER recipient before enqueueing the activity.

An emit node that queues an activity with no recipient leaves the outbox to fail later, with VultronOutboxToFieldMissingError, far from the cause. Resolving the CASE_MANAGER first makes the failure happen, and name its cause, at the node that builds the message.
Implements: PCR-08-001
Implements: PCR-08-002
PCR-08-016 MUST An emit node in a case-scoped trigger BT MUST fail fast (return FAILURE or raise immediately) when no routable CASE_MANAGER can be found.

A case-scoped message with no CASE_MANAGER to send it to reaches no one. Failing at once tells the caller that the message was not sent, at the node where the cause is known.
Extends: PCR-08-011
PCR-08-017 MUST NOT An emit node in a case-scoped trigger BT MUST NOT silently enqueue an activity with a None or empty to field.

An activity with no recipient is never delivered, but the trigger that queued it still reports success. The participant then waits for an answer to a message that nobody received.
Extends: PCR-08-011
PCR-08-018 MUST A trigger use case, and any BT it runs, MUST take a case-scoped message's sole to: recipient from the case's participant list. The recipient is the participant with CVDRole.CASE_MANAGER (PCR-08-005), never a helper that returns all participants, such as the roster index.

A participant messages only the CASE_MANAGER (PCR-08-005). A roster-wide recipient list sends case messages to actors that are not entitled to them, and those actors act on messages that the CASE_MANAGER never committed.
Implements: PCR-08-005

Testing

ID Priority Requirement Related
PCR-07-001 MUST Unit tests MUST verify that Announce(VulnerabilityCase) from the CASE_MANAGER creates a local replica when none exists.

A participant that cannot create its first replica from the CASE_MANAGER's copy cannot take part in the case at all. A unit test finds that failure before a demo or a deployment does.
PCR-07-002 MUST Unit tests MUST verify that Announce(VulnerabilityCase) from the CASE_MANAGER updates the local replica when one exists.

A replica that does not apply a later copy from the CASE_MANAGER stays at its old state while the case moves on. A unit test finds that failure before the replicas disagree in use.
PCR-07-003 MUST Unit tests MUST verify that Announce(VulnerabilityCase) from an actor that is NOT the CASE_MANAGER is rejected and logged at WARNING.

Refusing a copy from any sender other than the CASE_MANAGER is what keeps a replica from being rewritten by an untrusted actor (PCR-03-001). A test of the refusal, and of its WARNING log, keeps that protection from being lost without notice.
PCR-07-004 MUST Unit tests MUST verify that the context field is used to route incoming activities to the correct case handler.

If the context field stops selecting the replica, activities apply to the wrong case or to none. A test of the routing finds that failure where it starts.
PCR-07-005 MUST Unit tests MUST verify that activities with an unknown case context are queued and are dropped after timeout without updating any state.

The handling of unknown case context (PCR-06-001 to PCR-06-003) has two parts: hold the activity, and drop it later without changing state. A failure in either part loses an activity or writes untrusted state, so each part needs a test.
PCR-07-006 MUST Integration tests MUST verify the full bootstrap sequence. The sequence is: case creation → the bootstrap Create(VulnerabilityCase) reaches the participant → the participant creates its local replica → later case-scoped activities route correctly.

Each step of the bootstrap can pass its own unit test while the steps together still fail, for example when one step sends an activity that the next step does not accept. Only a test of the whole sequence shows that a new participant ends up with a working replica.
PCR-07-007 MUST Integration tests MUST verify the late-joiner sequence: Invite → Accept → CASE_MANAGER sends Announce(VulnerabilityCase) to new participant → new participant creates local replica.

A late joiner gets its replica by a different path than the first participants: through the Invite and its Accept. A test of that whole sequence shows that a participant that joins later also ends up with a working replica.
PCR-07-008 MUST Integration tests MUST verify that RmInviteToCaseActivity carries actor set to the CASE_MANAGER's ID, and that the invitee's RmAcceptInviteToCaseActivity is processed by the CASE_MANAGER (not the Case Owner).

If the Invite named the Case Owner as its actor, the invitee would answer the Case Owner, and the CASE_MANAGER would never record the join. A test of both messages keeps the invite exchange routed through the CASE_MANAGER (PCR-08-007, PCR-08-008).
Verifies: PCR-08-007
Verifies: PCR-08-008
PCR-07-009 MUST Integration tests MUST assert that no RM state-change activity is emitted with actor set to the invitee's ID from the Case Owner's context.

An RM change that the Case Owner emits under the invitee's id is a forged decision (PCR-08-010). The forgery passes every check that trusts the actor field, so only a test that looks for it can find it.
Verifies: PCR-08-014
Verifies: PCR-08-010
PCR-07-010 MUST Unit tests MUST verify that Announce(VulnerabilityCase) from an actor with no prior local trust record — no matching VultronReportCaseLink.case_manager_id and no invite trust anchor for the announced case ID — is rejected with a WARNING log entry and the case is NOT seeded in the receiver's DataLayer.

A first-contact copy from an unknown sender is the attack that PCR-03-004 prevents: it lets the sender seed a fake case. A test that the copy is refused, and the case not stored, keeps that protection in place.
Verifies: PCR-03-004

Participant Role Management

Defines the API for reading and mutating CVD roles on CaseParticipant, the one participant class shared by the core domain and the wire layer (ADR-0211). Requires the role-management methods, prohibits direct attribute mutation after construction, and mandates test coverage for each method.

File ID: PRM

Role Read API

ID Priority Requirement Related
PRM-01-001 MUST CaseParticipant MUST expose a read-only roles property that returns list[CVDRole], providing a stable public interface for iterating a participant's current roles without directly accessing the case_roles field.

A named property decouples callers from the internal storage field, enabling future changes to how roles are stored without updating every call site.
PRM-01-002 MUST CaseParticipant MUST expose a has_role(role: CVDRole) -> bool method that returns True when the participant holds the given role, False otherwise.

Provides a clear, named predicate for role-presence checks rather than requiring callers to write role in participant.case_roles.
PRM-01-003 MUST Core code in vultron/core/ MUST use participant.roles or participant.has_role(role) for role-presence checks and role iteration, never a direct read of participant.case_roles outside the CaseParticipant class.

Encapsulating storage access in the class boundary allows the internal representation to change without cascading updates across the core.

Role Mutation API

ID Priority Requirement Related
PRM-02-001 MUST CaseParticipant MUST expose an add_role(role: CVDRole, raise_when_present: bool = False) -> None method that adds a role to the participant's role set.

A named method provides a single place to enforce invariants (e.g. deduplication, logging) whenever a role is added.
PRM-02-002 MUST Unless raise_when_present=True, add_role() MUST ignore a role the participant already holds, raising no error and leaving the role set unchanged.

Idempotent add is safe for concurrent or repeated processing.
PRM-02-007 SHOULD add_role() SHOULD log an INFO-level message when it ignores a duplicate add.

An ignored add leaves no other trace. Logging the skip makes duplicate adds visible for debugging.
Extends: PRM-02-002
PRM-02-003 MUST add_role() MUST raise KeyError when raise_when_present=True and the given role is already present in the participant's role set.

Callers that require strict single-assignment semantics (e.g. role initialization guards) need a fail-fast path.
PRM-02-004 MUST CaseParticipant MUST expose a remove_role(role: CVDRole, raise_when_missing: bool = False) -> None method that removes a role from the participant's role set.

A named method provides a single place to enforce invariants whenever a role is removed.
PRM-02-005 MUST Unless raise_when_missing=True, remove_role() MUST ignore a role the participant does not hold, raising no error and leaving the role set unchanged.

Idempotent remove is safe for repeated processing.
PRM-02-008 SHOULD remove_role() SHOULD log an INFO-level message when it ignores the removal of a role the participant does not hold.

An ignored remove leaves no other trace. Logging the skip makes spurious removes visible for debugging.
Extends: PRM-02-005
PRM-02-006 MUST remove_role() MUST raise KeyError when raise_when_missing=True and the given role is not present in the participant's role set.

Callers that rely on strict presence checks before removal need a fail-fast path.

Core Layer Rules

ID Priority Requirement Related
PRM-03-001 MUST Core code in vultron/core/ MUST make every post-construction change to a CaseParticipant's case_roles through add_role() or remove_role(), never by direct mutation. Examples of direct mutation are participant.case_roles.append(...) and participant.case_roles = [...].

Direct mutation bypasses the class's encapsulation and any future invariant checks added to the mutation methods. Centralising mutations in named methods is the standard object-oriented pattern.
PRM-03-002 MUST Passing case_roles=[...] as a constructor argument when creating a CaseParticipant instance is permitted and does not violate PRM-03-001; the prohibition applies only to post-construction attribute mutation.

Constructor arguments are the canonical way to initialise an immutable value-object. This clarification prevents over-application of the rule.
See also: PRM-03-001 — context for the reader
PRM-03-003 MUST NOT Core code under vultron/core/ MUST NOT mutate participant_statuses on a CaseParticipant after construction except through the canonical CaseParticipant mutators. An example of direct mutation is participant.participant_statuses.append(...). The mutator methods themselves, in vultron/core/models/case_participant/participant.py, are exempt.

ParticipantStatus has two shapes that are not compatible (SDO-03-002, ADR-0036). When a status in the wire shape is added to a list of core-typed statuses, readers do not see it. They use an initial state, and the RM ladder of the participant resets with no signal. validate_assignment cannot stop this, because append is not an attribute assignment. Only the canonical mutators can check the shape. This rule applies PRM-03-001 to participant_statuses.

Wire Layer Interface Parity

ID Priority Requirement Related
PRM-04-001 MUST The wire-layer participant as_CaseParticipant (vultron/wire/as2/vocab/objects/case_participant.py) MUST expose add_role(), remove_role(), and has_role() methods with behavioral contracts equivalent to those on the core CaseParticipant: idempotent add/remove with optional raise-on-duplicate/missing flags, and a boolean presence check. Under ARCH-25-003 the two names are one class, which satisfies this by identity.

Callers that work with either domain or wire participant objects should not need to know which class they hold in order to manage roles.
PRM-04-002 SHOULD Wire-layer model_validator methods in CaseParticipant subclasses (e.g. ReporterParticipant, VendorParticipant) that initialise case_roles SHOULD call add_role() rather than assigning to self.case_roles directly, so that role-management logic is centralised.

Using add_role() in validators ensures any future invariant checks or logging added to add_role() apply uniformly during construction.

Testing Requirements

ID Priority Requirement Related
PRM-05-001 MUST Unit tests for CaseParticipant.add_role() MUST cover: (a) adding a new role, (b) idempotent re-add (no exception, INFO log), and (c) raise_when_present=True raising KeyError.

Each distinct branch of the method must be independently verified.
PRM-05-002 MUST Unit tests for CaseParticipant.remove_role() MUST cover: (a) removing a present role, (b) idempotent remove-when-missing (no exception, INFO log), and (c) raise_when_missing=True raising KeyError.

Each distinct branch of the method must be independently verified.
PRM-05-003 MUST Unit tests for CaseParticipant.has_role() MUST cover both the case where the role is present (returns True) and the case where it is absent (returns False).

Both branches of the boolean predicate must be verified.
PRM-05-004 SHOULD An architecture test SHOULD enforce that no Python source file under vultron/core/ (outside vultron/core/models/case_participant/participant.py) contains a direct case_roles mutation pattern (i.e. \.case_roles\s*= or \.case_roles\.append).

A machine-checkable rule prevents regression. Using a targeted file-content scan (e.g. ripgrep or stdlib pathlib glob + str search) on a small, bounded directory keeps it cheap (PRM-05-005).
PRM-05-005 MUST The architecture test of PRM-05-004 MUST complete within one second.

The one-second budget keeps the check from slowing the test suite, so it stays cheap enough to run on every change.
Extends: PRM-05-004

Project Documentation Structure

This specification defines the purpose, scope, and maintenance requirements for key project documentation files that guide AI agents and human developers.

File ID: PD

File Size Guidelines

ID Priority Requirement Related
PD-01-001 SHOULD Large modules with multiple responsibilities SHOULD be refactored into smaller cohesive modules

A module with many responsibilities is hard to read and hard to load as context, because a reader must go through code that is not related to the task. Many changes touch it, so parallel changes to it conflict more often. Small modules that each have one purpose keep each change small and easy to review.
PD-01-002 SHOULD NOT A notes/*.md file SHOULD NOT exceed 500 lines.

Large notes files force agents to filter through irrelevant content to find the specific context they need, increasing context window waste and the risk of missing relevant guidance.
PD-01-004 SHOULD An agent SHOULD split a notes/*.md file that exceeds 500 lines along topic-cluster boundaries, so that each new file covers one coherent "Load when" scenario.

A split at an arbitrary line gives two files that each hold part of a topic, so an agent must load both. A split at topic-cluster boundaries keeps each file narrowly focused on one "Load when" scenario.
Implements: PD-01-002
PD-01-003 SHOULD A notes/*.md file whose content spans multiple "Load when" scenarios that never co-occur in the same task context SHOULD be split into separate files, one per scenario cluster.

When a notes file covers several distinct agent tasks, any single load brings in guidance irrelevant to the current task. Single-scenario files make context loading precise and predictable.

Documentation Currency

ID Priority Requirement Related
PD-03-001 MUST notes/*.md files MUST be updated when implementation phases they describe are completed

Agents load notes/ as guidance for work that is not done yet. A note that still shows completed work as open sends an agent to do the work again, or to build against a design that the delivered code replaced.
PD-03-002 SHOULD Stale notes/*.md sections (cards) or whole files that are purely historical and contain no durable design guidance SHOULD be archived via append-history note to plan/history/YYMM/note/, rather than deleted. Source ID convention: NOTES-<file-stem>--<section-slug>. The learn skill Phase 5 drives section-level archival.

A historical section in notes/ uses context on every load and can mislead an agent about current design. A delete removes the text, but the archive keeps it in the project history, where a reader can still find it. The fixed source ID connects each archive entry to the file and section that it came from.
PD-03-004 MUST An agent MUST promptly archive a notes section or whole file that delivered code, an ADR or a spec entry fully supersedes. The agent archives it with append-history note to plan/history/YYMM/note/, rather than leave it as stale context.

A section that delivered code, an ADR or a spec replaced now disagrees with its replacement. An agent that loads both cannot tell which one is current.
PD-03-010 MUST When an agent archives every section of a notes/*.md file, the agent MUST remove the file from notes/ and delete its entry from notes/README.md.

A file with no sections left, or an index entry for a removed file, sends a reader to nothing.
Extends: PD-03-004
PD-03-005 MUST When an agent archives a notes section with append-history note, the entry body MUST include four parts. They are the archiving reason, a superseding pointer (code path, spec ID or docs page), a --- separator and the original section content verbatim.

The reason and the pointer tell a reader why the text left notes/ and where the current rule is. The verbatim content keeps the old text available without a search of the version history.
PD-03-011 MUST The source ID of an append-history note entry for a notes section MUST follow the NOTES-<file-stem>--<section-slug> convention.

One source ID convention lets a reader and the tools find the entry for a given section.
Extends: PD-03-005
PD-03-003 MUST Module paths referenced in notes/ MUST be updated to reflect canonical current locations whenever those paths change

An agent follows a path in a note to find the code. A path that is not current sends the agent to a file that does not exist, or makes it create a second module at the old location.
PD-03-006 SHOULD A workflow or tooling PR SHOULD update maintainer-facing documentation in the same PR.

Maintainers and agents follow the maintainer documentation to run each workflow and tool. If a change alters a tool and not its documentation, the next user follows steps that do not work now. The author of the change knows what changed, so an update in the same PR costs the least.
PD-03-014 MUST When a workflow or tooling PR leaves a needed maintainer-facing documentation update out, the PR MUST link a follow-up docs issue before merge.

An update left out of a PR is easy to forget once the PR merges. A linked follow-up issue keeps the gap visible and tracked until someone does the update. A tool cannot judge whether an update is needed, so the check asks the author to name the issue or to say why no update is needed.
Extends: PD-03-006
PD-03-007 MUST When an implementation or bug-fix PR changes behavior, interfaces, or architecture described in docs/, the PR MUST include the corresponding docs/ updates or a linked follow-up type:Task issue. Inline update is preferred for edits to existing pages, adding a single new page, or rewriting a single existing page. A deferred Task is acceptable only when the required update would simultaneously rewrite multiple docs/ pages.

A docs/ page that does not agree with the code misleads its readers, and nobody sees the difference until it is large. The author of the change has the context now, so an update in the same PR costs less than an update in a later session. A rewrite of several pages can be too large for one PR, so only that case can go to a Task, which keeps the gap tracked.
PD-03-008 MUST An agent MUST invoke the check-docs-sync skill on every implementation or bug-fix PR after the push and before the finalize steps (archive-history, learnings).

When the check runs after the push, the docs work and CI run at the same time. The check finds and applies any required docs/ updates in the same PR, before the finalize steps record the PR as complete.
PD-03-013 MUST NOT An agent MUST NOT end the session until its PR's Docs: line names updated pages, "no docs impact" with a reason, or the deferred issue.

A step that leaves no record can be skipped with no trace, and then a page that is not correct merges without notice. The final line replaces the placeholder that create-pr writes. A placeholder that stays in the field shows an unfinished check on the PR, where PD-03-009 enforces it.
Extends: PD-03-008
PD-03-009 MUST pr-triage MUST independently determine which docs/ pages an implementation or bug-fix PR's diff affects, whether or not the diff touches docs/, and compare that determination with the PR body's Docs: field. A missing or still-placeholder Docs: field is a FAIL finding; an affected page the PR neither updated nor deferred is an IMPROVE finding; and so is a deferral that does not name an existing follow-up type:Task or type:Concern issue listing the affected pages, or that falls outside what PD-03-007 permits deferring (an update that would rewrite multiple docs/ pages at once).

A docs check that runs only when the PR already changed docs/ can never find a page that the author forgot. Only the review check reaches PRs that a person wrote and the fix rounds of pr-execute. The reviewer makes its own decision and does not trust the Docs: line of the author. Thus it can find a "no docs impact" that the author wrote without a check. A type:Concern deferral still counts, because deferrals filed before PD-03-007 named a Task were Concerns.
Verifies: PD-03-007

Documentation Build Validation

ID Priority Requirement Related
PD-04-001 MUST mkdocs build --strict MUST pass without warnings before any changes to docs/ directory files are staged for commit

A warning from a docs build often shows a broken link, a page that is not in the navigation, or an include that failed. --strict makes each warning fail the build. When the author runs it before staging, the author fixes the problem before the commit, and the problem does not get to the published site.
PD-04-002 MUST Validation MUST occur after markdown linting (via .claude/skills/format-markdown/SKILL.md) and before test runs, in the build-and-test workflow documented in .claude/skills/build-docs/SKILL.md

The markdown linter can fix files, and the build must check the final text, so the build runs after the linter. The docs build is fast compared with the test suite, so a docs error stops the workflow before the long test run.
PD-04-003 SHOULD Agents SHOULD run uv run mkdocs build --strict locally when modifying docs/ files to catch issues before staging for commit, reducing CI failures and improving development velocity

A local build finds a docs error in a short time. The same error found in CI costs a push and a wait for the CI run.

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 Kinds

Each kind of ask declares the replies that close it, its expiry consequence, and a default deadline.

ID Priority Requirement Related
ASK-03-005 MUST The default deadline duration for each ask kind MUST be configurable through ActorConfig, with a documented fallback default for kinds that declare no override.

Urgency differs by kind and by deployment; the duration is safe to configure because it travels on the wire (ASK-03-004).

Expiry and Reaping

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

ID Priority Requirement Related
ASK-05-002 MUST The system MUST expose a general-purpose trigger that reaps expired outstanding asks for an actor.

Reaping is a Sentinel concern, and a Sentinel operates on the call-in surface with no BT call-out point, so the reaper belongs outside core.

Processing Faults

How a receiver tells an authenticated sender that it could not process what was sent.

ID Priority Requirement Related
ASK-07-011 MUST In this implementation, the inbox MUST send the fault of ASK-07-010 when the received use case dispatched for an activity raises. This holds for every use case, not only for the trees that commit an act. The one exception is the use case for a received Create(ProcessingFault), which ASK-07-019 leaves unanswered.

The receiver's internal failure is a raise out of the use case, and the inbox is the one place every dispatch passes through, so answering there covers every use case at once.
Implements: ASK-07-010
ASK-07-016 MUST The inbox MUST queue the fault of ASK-07-010 after the DataLayer transaction that the act opened has rolled back.

A fault queued inside the rolled-back transaction would be undone with the act.
Implements: ASK-07-010
ASK-07-017 MUST The inbox MUST answer a deferred activity replayed from the pending queue (IE-06-004) only when that activity is dead-lettered.

A replay that fails is retried until it is dead-lettered, so the dead-letter step is the first point at which no retry follows (ASK-07-014).
Implements: ASK-07-014
Uses definition from: IE-06-008
Uses definition from: IE-06-004
ASK-07-018 MUST The inbox MUST derive the fault id from the failed activity's id and the failure class.

A derived id makes a repeated failure rebuild the same fault, so the sender is answered once (ASK-07-015).
Implements: ASK-07-015

Prototype Shortcuts

Permissible shortcuts and relaxed constraints for the prototype stage, supporting iterative development while preserving traceability of production requirements.

File ID: PROTO

Authentication

ID Priority Requirement Related
PROTO-01-001 MAY Omit cryptographic authentication for agent-to-agent communication.

Cryptographic authentication needs key management and signature checks, and these do not change the protocol behavior under test. The prototype runs in local test and demo setups, so it can omit authentication and test the protocol logic first. The shortcut is for the prototype only. A production node must authenticate case update notifications (CM-06-004).
Supersedes: CM-06-004

Federation

ID Priority Requirement Related
PROTO-02-001 MAY Assume all actors are local to a single ActivityPub server.

Many tests and some demos host every actor in one server process. In those setups, the prototype does not need to find or reach actors on other servers, so the work stays on the CVD protocol logic.
PROTO-02-002 MAY Post direct messages to an actor's inbox without federation or cross-server routing.

ActivityPub federation adds actor discovery, server-to-server delivery rules and remote failure handling. The protocol logic needs only that a message gets to the recipient's inbox. A direct post does that with much less code, and the protocol behavior stays the same.

Performance

ID Priority Requirement Related
PROTO-03-001 SHOULD NOT Use algorithms with exponential or worse time complexity.

Exponential time can make a small case or a test stop with no clear cause. Even in a prototype, that cost blocks tests and demos, so a simple algorithm that does not grow exponentially is the better choice.
PROTO-03-002 SHOULD Prefer the simplest algorithm when multiple options exist, even if less efficient.

In the prototype, code changes often as the design changes. Simple code is easier to read, review and change. The data sets are small, so a less efficient algorithm costs little.
PROTO-03-003 SHOULD Implement straightforward optimizations that do not significantly increase complexity.

Some optimizations cost almost nothing to read and keep, for example a set lookup in place of a list scan. They keep tests and demos fast and add no design risk, so there is no reason to wait for production.
PROTO-03-004 SHOULD Document known unimplemented optimizations in implementation notes for future reference.

An optimization that is known but not done can be forgotten. A note records it, so the work can start when production needs it, with no new investigation.

Production Deferral

ID Priority Requirement Related
PROTO-04-001 SHOULD Specification files SHOULD mark a production-only requirement PROD_ONLY by giving it scope: [production], so production-only requirements can be systematically identified and deferred during the prototype stage.

The prototype omits some production requirements, such as authentication and federation. Without a mark, a reader cannot tell a deferred requirement from one that the prototype fails to meet. The mark lets a reader list the deferred requirements and leave them out of prototype work.
PROTO-04-002 SHOULD Review specifications to identify requirements that should carry the PROD_ONLY tag.

Production-only requirements occur in many spec files, and an author can forget the mark. A review finds the requirements that need it, so prototype work does not go to them and readers do not count them as gaps.

Case Prioritization

ID Priority Requirement Related
PROTO-05-001 MAY Use a stub always-engage policy (AlwaysPrioritizePolicy) in place of a real prioritization framework.

Case prioritization, for example with SSVC, is a policy decision outside the protocol state machines. A stub that always engages lets every case go through the full workflow, so tests and demos reach all protocol states with no real decision framework.

Backward Compatibility and Change Completeness

ID Priority Requirement Related
PROTO-08-001 MUST NOT Add backward-compatibility shims when refactoring, renaming, moving, or removing code. Shims include re-export stubs, import aliases, wrapper functions, and deprecation stubs that exist solely to preserve old import paths or call signatures.

Without shims a failing import immediately signals a missed call site; with a shim the missed update is invisible and accumulates as technical debt
PROTO-08-002 MUST Complete every code change fully — all call sites for a renamed, moved, or removed symbol MUST be updated in the same commit as the symbol change.

If a rename leaves some call sites unchanged, the code is broken between commits, and a bisect or a revert can stop on a broken commit. When the symbol and all its call sites change in one commit, each commit stays consistent.
PROTO-08-003 MUST NOT Preserve an old API, import path, field name, or function signature solely for backward compatibility.

The prototype has no external consumers of its code API. An old name kept only for compatibility gives two names for one thing, and readers and agents can use the wrong one. When the old name goes, every caller uses the current name.
PROTO-08-004 SHOULD Follow a documented deprecation cycle with migration guidance when external consumers of the API exist.

When external code depends on the API, a sudden removal breaks that code with no warning. A documented deprecation cycle gives those consumers time and instructions to change before the old form goes.

Performance Testing

ID Priority Requirement Related
PROTO-07-001 MAY Performance tests and performance assertions MAY be skipped or marked as expected failures during the prototype stage

Premature performance work distracts from correctness and architectural clarity; defer until exiting the prototype phase

Received-Side Status Authorization

Requirements for the authorization model governing how a CASE_MANAGER adopts an inbound participant's reported CaseStatus as canonical (StatusAdoptionGate) and runs the embargo teardown an adopted value calls for, which the adoption also authorizes (ADR-0166). Derived from ADR-0046 and IDEA-1836 planning session.

File ID: RSH

StatusAdoptionGate

Controls whether a participant's reported CaseStatus is adopted as canonical by the CASE_MANAGER.

ID Priority Requirement Related
RSH-01-001 MUST add_participant_status_tree MUST include a StatusAdoptionGate node positioned after AppendParticipantStatusNode and before any canonicalization step.

StatusAdoptionGate of ADR-0046 — separates the "record the claim" step from the "adopt the claim as canonical" decision.
RSH-01-002 MUST StatusAdoptionGate MUST be implemented as a Fallback with two children: (1) CheckIsCaseOwnerNode as a hard bypass and (2) a CaseOwnerApprovesStatusUpdate Evaluator call-out point.

CASE_OWNER reports are authoritative by definition (gospel bypass). Non-owner reports pass through a configurable approval gate per ADR-0210.
Implements: RSH-07-006
RSH-01-004 MUST Embargo teardown and other canonical-state side-effects in add_participant_status_tree MUST run only after the canonical CaseStatus ledger write of RSH-01-003.

Writing the adopted status first lets the termination name the adopted signals as its cause, and lets every replica replay the cause before its effect. The adoption also authorizes the teardown the adopted value calls for, so no second gate sits between the write and the teardown, and both run in one CASE_MANAGER act (ADR-0210).
Uses definition from: RSH-01-003

ThreatTerminationBranchNode

Node that triggers embargo teardown on any of the three threat-signal CaseStatus flags.

ID Priority Requirement Related
RSH-03-002 MUST NOT ThreatTerminationBranchNode MUST NOT gate teardown on sender role (e.g., CASE_OWNER). Authorization is the responsibility of StatusAdoptionGate; by the time this node runs, the canonical write is already authorized.

By the time this node runs the canonical write is already authorized, by StatusAdoptionGate in add_participant_status_tree, where the sender is the asserting participant. That sender is not necessarily CASE_OWNER: the gate's call-out may approve a non-owner's report, so a duplicate CASE_OWNER gate here would block a legitimate teardown.
RSH-03-003 MUST add_participant_status_tree MUST tear an embargo down through ThreatTerminationBranchNode, after the canonical write.

The node belongs in the tree that writes canonical state. A received Add(CaseStatus) writes none: it is admitted only at a participant replica, from the CASE_MANAGER, whose own teardown the replica leaves to the committed entry (RSH-04-005, RSH-03-004).
RSH-03-005 MUST NOT add_participant_status_tree MUST NOT contain PublicDisclosureBranchNode.

PublicDisclosureBranchNode covered only CS.P and predates the adoption-gate design (RSH-03-001). ThreatTerminationBranchNode covers all three signals.
Extends: RSH-03-003
RSH-03-006 MUST NOT add_case_status_tree MUST NOT contain ThreatTerminationBranchNode.

A received Add(CaseStatus) is admitted only at a participant replica, from the CASE_MANAGER. The replica leaves the CASE_MANAGER's teardown to its committed entry (RSH-03-004), so a teardown node in this tree would act a second time.

CaseStatus Emission Authority and Outbound Emit Invariant

Specifies which actors may emit Add(CaseStatus) directly and mandates that every CASE_MANAGER-side EM or PXA state mutation is followed by a canonical CaseStatus ledger write. CaseStatus is the only protocol channel for communicating EM and PXA state changes across actors; omitting the emit leaves all participant replicas stale until the next round-trip.

ID Priority Requirement Related
RSH-04-006 MUST In this implementation, one shared BT node, EmitCaseStatusUpdateNode, MUST make the CaseStatus record of RSH-01-003, RSH-04-002 and RSH-04-003. It writes the new CaseStatus directly to case.case_statuses, commits the CaseLedgerEntry and emits Add(CaseLedgerEntry).

One node keeps every tree that changes EM or PXA from carrying its own copy of the commit and announce.
Implements: RSH-01-003
Implements: RSH-04-004
See also: RSH-04-002 — context for the reader
See also: RSH-04-003 — context for the reader
RSH-04-010 MUST add_participant_status_tree MUST run EmitCaseStatusUpdateNode when StatusAdoptionGate passes.

The adoption gate decides whether the reported status becomes canonical. Running the shared node on that decision is how the adopted status reaches the ledger (RSH-01-003).
Extends: RSH-04-006
RSH-04-011 MUST NOT EmitCaseStatusUpdateNode and add_participant_status_tree MUST NOT reach the canonical write indirectly. They never route through add_case_status_tree, and never emit a self-addressed Add(CaseStatus, target=<case>/statuses) to the CASE_MANAGER.

A self-addressed message would make the announce trigger the ledger write instead of follow it, and would put an already authorized write through a second adjudication (RSH-04-008).
Extends: RSH-04-006

RM Anomaly Notification Policy (non-adjacent jumps and backward regressions)

When the receiver detects an RM transition anomaly — either a non-adjacent forward jump (sender skipped intermediate states) or a backward regression (sender reports a state earlier on the RM progress scale than the receiver has already observed) — it must act correctly and non-silently. Because CVD is inherently asynchronous, anomalies are detected at receipt time (t₁ > t₀ when the event occurred), and silence at that point breaks observability for both parties. Derived from ISSUE-2258 and ADR-0067.

ID Priority Requirement Related
RSH-06-003 MUST When the receiver accepts a non-adjacent forward RM jump or refuses a backward RM regression, it MUST log a WARNING. The WARNING names the sender, the observed rm state before and after, and the anomaly type, gap or regression. This holds for every received write of a participant's RM state that RSH-06-006 names.

Because CVD is inherently asynchronous, protocol anomalies are detected at receipt time (t₁ > t₀ when the event occurred). Silent handling makes diagnosis impossible for both parties and breaks protocol observability.
Uses definition from: RSH-06-006

Conservative Default Authorization Policy for Status Gates

Adopting a non-owner's reported P, X or A value waits by default for the Case Owner's authorization, which also authorizes the embargo teardown the adopted value calls for (ADR-0210). A permissive policy is a deployment's explicit choice. Derived from CONCERN-2092 and ADR-0076; the mechanism is amended by ADR-0080 (CONCERN-2812, CONCERN-2809) — see RSH-07-004.

ID Priority Requirement Related
RSH-07-004 MUST Each status authorization gate MUST be composed as a conversation-state routing subtree per ASK-02-001. It is never a single-tick Evaluator call-out that answers the authorization question inline.

When the gate first needs authorization, no answer exists. An Evaluator that asks "is this approved?" can thus only answer no, and no path can then reach the authorization model of ADR-0046 and ADR-0076. The gate routes on four conditions: authorization is recorded, refused, requested and not answered, or not requested. This lets the gate send the request, end the tick, and pass when the answer is in the ledger.
Refines: BT-18-014 — BT-18-014 generalises the criterion that replaced this gate's call-out mechanism with a routing subtree.
Refines: ASK-02-001
RSH-07-005 MUST NOT A status authorization gate MUST NOT be satisfied by relaxing its default to a permissive backend in order to make a blocked path proceed.

STATUS_AUTHORIZATION_PERMISSIVE is for deployments with trusted participants and for demos (RSH-07-003). If a deployment uses it to avoid a gate that cannot pass, a protocol guarantee becomes a configuration setting. A deployment that copies this setting then loses the check by the Case Owner without a decision to drop it.
RSH-07-003 MAY An implementation MAY configure a permissive backend (e.g., AlwaysSucceed) for CaseOwnerApprovesStatusUpdate where all admitted participants are trusted and the cost of Case Owner approval is unacceptable.

Demo and trusted-participant deployments need automated sentinel behavior without ceremony; the conservative posture is the default. A permissive backend is the Case Owner delegating its approval in advance, keeping the authority (VP-11-006), configured and documented by the operator (RSH-07-007). Role-differentiated, probabilistic or any CallOutBackendFactory-conformant backend is also valid (ADR-0076). The delegation covers the teardown, which adoption authorizes (ADR-0210).
RSH-07-007 MUST An implementation that configures a permissive backend for CaseOwnerApprovesStatusUpdate MUST configure it explicitly and document that choice.

A permissive backend lets any admitted participant change canonical case state with no Case Owner confirmation. Making it explicit and documented keeps that a visible operator decision, never a silent default (ADR-0076). Split from RSH-07-003, which states the permission.
Extends: RSH-07-003

One Move, One Mover — Received-Side Write Subject and Pipeline

A protocol state transition may reach a receiver in more than one wire shape: the activity that performed the move (TentativeReject(Offer(VulnerabilityReport))) and a declaration of the resulting state (Add(ParticipantStatus) carrying rmState). These are two layers of one move, not competing encodings. Authority is a property of the pipeline, not of the message: the mover announces, the CASE_MANAGER adjudicates and commits, replicas apply the ledger. Derived from CONCERN-3473 and ADR-0108.

ID Priority Requirement Related
RSH-08-005 MUST A received-side tree MUST record a received RM declaration against the sending actor (request.actor_id), never against the receiving actor whose store the tree executes in.

How this codebase meets RSH-08-001; split from it so RSH-08-001 states only what other participants observe (MS-12-010).
Implements: RSH-08-001
RSH-08-003 MUST A received-side tree MUST write participant or case state only when the executing actor holds CVDRole.CASE_MANAGER for the case (BT-17-001). This covers every write the tree makes as an effect of an inbound activity. The one exception is a participant whose ledger stream is paused. It applies an embargo-ending notice that the CASE_MANAGER sends it (CM-31-010).

If a received-side tree writes state at every inbox, Add(EmbargoEvent), Remove(EmbargoEvent) or Add(CaseStatus) from any sender can change the state of a replica. The tree also applies an activity that gets to a replica by cc or by incorrect routing, without the decision or the sender check of the CASE_MANAGER (PCR-03-001). A paused ledger stream cannot carry the end of an embargo, so the replica applies that one notice from the CASE_MANAGER directly (ADR-0116).
See also: BT-17-001 — context for the reader
RSH-08-010 MUST A replica without the CASE_MANAGER role that receives such an activity directly MUST store it and write no participant or case state. The exception of RSH-08-003 still applies. It takes the resulting state from the Add(CaseLedgerEntry) broadcast (PCR-03-001).

The replica keeps the activity it received, so a later entry can name it, but its case state comes only from the CASE_MANAGER's committed entries. Otherwise its state would differ from every other replica at the same ledger position.
Extends: RSH-08-003
See also: PCR-03-001 — context for the reader
RSH-08-004 MUST Each ledger semantic_type the CASE_MANAGER commits MUST have a replica apply node reachable from create_add_log_entry_tree, or a recorded no-effect declaration. A no-effect declaration records that the event has no replica-side effect.

A replica gets case state only from replayed ledger entries (RSH-08-003, ADR-0108). Thus a committed semantic_type with no apply node keeps every replica from seeing that change.
RSH-08-011 MUST NOT A change that gates a received-side effect under RSH-08-003 MUST NOT land before the replay node for the transition that effect wrote exists.

Once the effect is gated, a replica no longer writes the transition on direct receipt. If the replay node does not exist yet, the replica loses its only path to the change.
Uses definition from: RSH-08-004
Uses definition from: RSH-08-003

Whole Accept or Reject of a Received Status

A received Add(ParticipantStatus, target=<participant>/statuses) or Add(CaseStatus, target=<case>/statuses) states a whole status, so the CASE_MANAGER accepts it as sent or refuses all of it. It never records a status the sender did not send. Derived from ADR-0107 and ISSUE-3741.

ID Priority Requirement Related
RSH-09-007 MUST In this codebase, the failure path of the behavior tree that applies the entry MUST emit the fault that RSH-09-013 requires. This is a tree-structural guarantee: the node that applies the status never emits the fault as a side effect.

How this codebase meets RSH-09-013; split so that RSH-09-006 and RSH-09-013 state only what other participants observe (MS-12-010). It keeps the apply node a pure domain check that returns FAILURE on violation and the emission a composable side-effect, consistent with protocol-significant behavior living in the tree (BTND-01).
Implements: RSH-09-013
RSH-09-008 MUST When CheckParticipantStatusAcceptableNode refuses an Add(ParticipantStatus, target=<participant>/statuses), the received use case MUST return HandlerResult.refused, which the inbox maps to a rejected InboxOutcome rather than 202 Accepted / processed.

Only the inbox outcome tells a sender that the receiver refused or accepted an update. If a refused status assertion returns 202 Accepted / processed, the sender believes that the CASE_MANAGER recorded the status. The view of the case of the sender then becomes different, and no signal shows this.
Extends: RSH-09-002

Response Format

The Vultron protocol uses ActivityStreams activities for both requests and responses. When handlers process inbound activities, they generate response activities (Accept, Reject, Update, etc.) sent to the originating actor or other participants.

File ID: RF

Accept Response

ID Priority Requirement Related
RF-02-006 MUST This codebase MUST carry the Offer inline as the object of an Accept, as an inline typed activity object such as RmSubmitReportActivity or EmProposeEmbargoActivity.

How this codebase meets RF-02-004; split from it so RF-02-004 states only what other participants observe (MS-12-010). Carrying the Offer inline rather than by reference is a shortcut of this prototype reference implementation, not a protocol rule.
Refines: RF-02-004
RF-02-008 MUST This codebase MUST reject a bare string ID as the object of an Accept of an Offer at construction time.

A check at construction time stops a wrong shape before any code sends it. An Accept built with a bare ID would reach the peer without the inline Offer that RF-02-006 requires.
Implements: RF-02-006
RF-02-007 MUST This codebase MUST carry the Invite inline as the object of an Accept of an Invite. The Invite is a full inline typed activity object, such as RmInviteToCaseActivity or EmInviteToEmbargoOnCaseActivity.

How this codebase meets RF-02-005; split from it so RF-02-005 states only what other participants observe (MS-12-010). Carrying the Invite inline rather than by reference is a shortcut of this prototype reference implementation, not a protocol rule.
Refines: RF-02-005
RF-02-009 MUST This codebase MUST reject a bare string ID as the object of an Accept of an Invite at construction time.

A check at construction time stops a wrong shape before any code sends it. An Accept built with a bare ID would reach the invitee's peers without the inline Invite that RF-02-007 requires.
Implements: RF-02-007

Reject Response

ID Priority Requirement Related
RF-03-004 MUST This codebase MUST carry the Offer inline as the object of a Reject, refusing a bare string ID there at construction time.

How this codebase meets RF-03-003; split from it so RF-03-003 states only what other participants observe (MS-12-010). Carrying the Offer inline lets the receiver read the Offer's type without a dereference, a shortcut of this prototype reference implementation rather than a protocol rule (AKM-05-003).
Refines: RF-03-003

TentativeReject Response

ID Priority Requirement Related
RF-04-004 MUST This codebase MUST carry the Offer inline as the object of a TentativeReject, refusing a bare string ID there at construction time.

How this codebase meets RF-04-003; split from it so RF-04-003 states only what other participants observe (MS-12-010). Carrying the Offer inline lets the receiver read the Offer's type without a dereference, a shortcut of this prototype reference implementation rather than a protocol rule (AKM-05-003).
Refines: RF-04-003

Response Timing

ID Priority Requirement Related
RF-07-001 MUST NOT Response generation MUST NOT delay inbox acknowledgment

A sender whose POST waits on response generation can time out and retry, which produces duplicate deliveries, and a slow handler would hold the inbox for other senders. A response travels as its own activity (RF-06-001), so the acknowledgment needs nothing from it.

Response Correlation

ID Priority Requirement Related
RF-08-002 MUST This codebase MUST enforce the inReplyTo rule with a model_validator on Accept, Reject and the other response activity classes, not by call-site convention.

Call-site convention (setting inReplyTo manually at every factory call site) is fragile: new factory paths can forget it, and there is no compile-time or model-validation enforcement. A model_validator makes the invariant intrinsic to the type and impossible to bypass silently.
Implements: RF-08-001
RF-08-003 MUST NOT The inReplyTo validator MUST NOT let a response activity be constructed with a None or missing inReplyTo.

A response with no inReplyTo does not say which activity it answers. When the validator stops it at construction time, no code can send it.
Extends: RF-08-002

Report Management Behavioral Requirements

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

File ID: RMB

RM Write-Boundary Transition Validation

Requirements for RM state write paths to validate source→target transition validity before persisting a ParticipantStatus snapshot. Complements CSB-16 (VFD/PXA write-boundary validation) and SDO-02-002 (dimension object transition contract) by requiring that the BT write node itself is fail-closed regardless of upstream guard coverage.

ID Priority Requirement Related
RMB-15-001 MUST Before it persists an RM state to a ParticipantStatus snapshot, a BT node or helper MUST check the transition with is_valid_rm_transition(). The check confirms that the RM state machine permits (current_rm_state → target_rm_state). A same-state write is permitted (status confirmation).

Some sites write ParticipantStatus.rm directly, for example with RmDimension(state=target), and do not use the transition() contract in SDO-02-002. The BT guards before the write node are necessary but not sufficient. A weak or missing guard lets an incorrect RM jump reach the write node with no check. A check at the write boundary refuses an incorrect RM transition, whatever the guards do.

ECA Details

Preconditions

- A non-None RM target state is passed to a ParticipantStatus write node

Steps

1. [write_node] Read the participant's current RM state from the DataLayer → Current RM state available
2. [write_node] If target == current, proceed. If is_valid_rm_transition(current, target) is True, proceed. Otherwise return Status.FAILURE. → Only valid transitions or same-state writes reach the DataLayer

Postconditions

- No ParticipantStatus with an illegal RM state jump is persisted

Refines: BTND-10-001
RMB-15-002 MUST On an illegal jump or a backward move, the BT node that writes the RM state MUST return Status.FAILURE without writing to the DataLayer.

A FAILURE with no write leaves the stored RM state as it was, so a refused transition never reaches the DataLayer or a replica.
Extends: RMB-15-001

Semantic Extraction

The inbox handler extracts semantic meaning from ActivityStreams activities by matching activity type and object type patterns. This semantic type determines which handler function processes the activity.

File ID: SE

Pattern Matching

ID Priority Requirement Related
SE-01-001 MUST The system MUST match activities using activity type and object type patterns

The meaning of a message depends on its verb and on the object of the verb. An Offer of a report and an Offer of a case ask for different things. If the matcher reads only the activity type, it sends both messages to one handler.
SE-01-005 MUST The semantic extraction algorithm MUST rehydrate a URI string reference before pattern matching.

This is how this codebase meets SE-01-002. A pattern matches an object by its type, and a bare URI has no type, so a reference must become the object before matching (SE-01-006).
Implements: SE-01-002
SE-01-008 MUST The semantic extraction algorithm MUST handle both fully expanded objects and unresolved URI strings defensively.

A rehydration can fail, so extraction can still meet a URI string after it. If it assumes an expanded object, an unresolved reference raises where it should give a defined result.
Refines: SE-01-002
SE-01-003 MUST NOT find_matching_semantics() MUST NOT log a WARNING, store a dead-letter record or raise for an activity whose object stayed unresolved after rehydration.

The matcher only classifies: such an activity gets the UNKNOWN_UNRESOLVABLE_OBJECT sentinel (VAM-01-009), and its handler logs the WARNING and stores the dead-letter record (SE-04-007). One place for each step keeps the WARNING from being logged twice, and keeps the matcher free of the DataLayer it would need to store a record.
SE-01-004 MUST Pattern matching MUST support type/subclass matching semantics for actor/object classes

Vultron extends the ActivityStreams vocabulary with subclasses of its types. If a pattern matches only exact types, it must list each subclass. An activity with a new subtype then goes to UNKNOWN.
SE-01-006 MUST NOT An ActivityPattern's object_ type constraint MUST NOT be satisfied by a bare URI that is still unresolved after rehydration. No pattern is exempt.

A bare object at match time is an object that the receiver could not resolve, so its type is unknown. If a pattern ignores the type, the activity goes to the first pattern for its verb. For example, an Announce of an embargo given by its id becomes ANNOUNCE_VULNERABILITY_CASE. If no pattern matches, the semantic type is UNKNOWN_UNRESOLVABLE_OBJECT. The receiver can respond to that result: it can get the object (AKM-05-003).
Extends: SE-01-005
SE-01-007 MAY A bare URI in an activity's target, origin, context or to MAY satisfy an ActivityPattern's type constraint on that field, except where SE-08-004 requires strict=True.

A case in target, origin or context travels as its URI by rule (MV-10-009, AKM-02-003); the stub travels only as a preview in an Invite's object (MV-10-002). A pattern that refused a bare case URI there would refuse well-formed activities. Only the object names the thing the activity acts on.
SE-01-009 MUST NOT An ActivityPattern's object_ constraint MUST NOT be satisfied by a typed reference that carries a preview, unless the pattern requires that form of its object.

A preview is not the object it previews (MV-10-013). A pattern that matched the previewed case reference by its type would read a stub Invite as the full-case Invite, or an Announce of a preview as a case copy that seeds a replica. Two patterns that differ only in the form they require, a previewed reference or a whole object, each match only their own form, so the stub Invite and the full-case Invite are told apart without a fetch (ADR-0205).
Implements: MV-10-013

Semantic Type Assignment

ID Priority Requirement Related
SE-02-001 MUST The system MUST assign MessageSemantics enum value via find_matching_semantics()

With one classification function, the same rules in the same order give the semantic type of each received activity. A second code path can give one activity two semantic types, and the order checks of the registry do not cover that path.
SE-02-002 MUST The function MUST return the first matching semantic type

More than one pattern can match an activity. The registry puts the most specific patterns first (SE-03-002). Because the matcher returns the first match, that order decides the result. Any other rule lets a general pattern win over a specific one.

Pattern Registry

ID Priority Requirement Related
SE-03-001 MUST SEMANTIC_REGISTRY MUST contain an entry with a non-None pattern for every supported MessageSemantics value except the UNKNOWN and UNKNOWN_UNRESOLVABLE_OBJECT sentinels

Matching must reach each supported semantic type. If it cannot, a correct activity of that type goes to UNKNOWN. The two sentinels are the exception. Their entries have no pattern, because find_matching_semantics() sets them by fallback logic, not by a pattern.
SE-03-002 MUST Pattern registry MUST be ordered from most specific to least specific

find_matching_semantics() returns the first match (SE-02-002). If a general pattern comes before a specific pattern for the same verb, the specific pattern never matches. Its activities then go to the wrong handler.
SE-03-003 MUST Every ActivityPattern entry in SEMANTIC_REGISTRY MUST discriminate on at minimum both Activity type AND Object type

A pattern without an object-type constraint would match every activity of that verb type regardless of payload, causing misrouting when multiple semantics share an outer Activity type
SE-03-004 MUST NOT An ActivityPattern MUST NOT discriminate on the sender's identity or role. It matches only the activity's type and the types of its object, target, origin, context and recipients.

A semantic type says what an activity is; the sender's standing says whether it is permitted (ADR-0152). A matcher that read the sender would need to know who holds the CASE_MANAGER role for each case, and would give one shape two meanings depending on who sent it.
SE-03-005 MUST When the CASE_MANAGER performs the same verb on the same kind of object as a participant, its activity MUST match the participant's pattern.

One shape has one meaning. A CASE_MANAGER activity that matched its own pattern would need a pattern that reads the sender, which SE-03-004 forbids.
Derives from: SE-03-004
SE-03-006 MUST The handler's sender-entitlement check (HP-01-006, HP-01-007) MUST decide, after routing, whether the sender of a matched activity may send it.

The pattern does not read the sender (SE-03-004), so routing cannot refuse a sender. The handler knows the case and its roles, so it is the one place that can judge the sender's standing.
Uses definition from: HP-01-006
Uses definition from: HP-01-007

Unrecognized Activity Handling

ID Priority Requirement Related
SE-04-001 MUST The system MUST log unrecognized activities at WARNING level

An unrecognized activity often comes from a peer that uses a form Vultron does not support, or from a pattern defect in Vultron. In both cases, the receiver does not act on the message. The WARNING lets an operator see that the receiver dropped a message.
SE-04-002 MUST The system MUST route an UNKNOWN activity to UnknownUseCase and an UNKNOWN_UNRESOLVABLE_OBJECT activity to UnresolvableObjectUseCase.

The two sentinels have different causes. An UNKNOWN activity has a shape that no registered pattern knows (VAM-01-007). An UNKNOWN_UNRESOLVABLE_OBJECT activity has an object that the receiver could not resolve (SE-01-003), which is a data gap that can close later. Each cause needs its own handler: only the second keeps the activity for a retry.
SE-04-006 MUST UnknownUseCase MUST answer an UNKNOWN activity with a REFUSED verdict, not an exception.

An activity that no pattern knows is often from a peer that uses a form Vultron does not support. That is not a receiver defect. The dispatcher lets every handler exception propagate (DR-03-002), so a raise would report a bug that does not exist. A REFUSED verdict records that the receiver did not act on the activity.
Extends: SE-04-002
SE-04-007 MUST UnresolvableObjectUseCase MUST log a WARNING naming the unresolvable URI, store the activity in a dead-letter record (SE-04-003), and return a REFUSED verdict, not an exception.

An unresolvable object URI is not a programming error; it is a data completeness issue that may resolve later. The WARNING shows the problem to an operator, and the dead-letter record keeps the activity so that the receiver can try it again. The receiver did not process the activity, so the verdict is a refusal, and a raise would report a bug that does not exist (DR-03-002).
Extends: SE-04-002
Uses definition from: SE-04-003
SE-04-003 MUST A dead-letter record for an unresolvable-object_ activity MUST include the full activity JSON, the unresolvable URI, the actor ID, and a timestamp.

The record must keep the data that the receiver needs to try the activity again when its object becomes available. The record must also show who sent the activity and when. Without the full activity and the URI, an operator cannot find the cause or replay the activity.
SE-04-005 MUST The receiver MUST store each dead-letter record for an unresolvable-object_ activity in a DataLayer collection open to administrative review and retry.

A record that no one can read or replay keeps the activity but does not let an operator act on it.
Extends: SE-04-003
SE-04-004 MUST For any future synchronous processing path (non-background), an UNKNOWN_UNRESOLVABLE_OBJECT activity MUST return HTTP 422 with an explanatory error body identifying the unresolvable URI

A synchronous caller waits for the answer, so the receiver can tell it why it did not process the activity. A 422 status tells the sender that the request was correct in form but that the receiver could not act on it. The URI in the response tells the sender which object to send inline or to make available.

Pattern Validation

ID Priority Requirement Related
SE-05-001 MUST All patterns MUST have corresponding MessageSemantics enum value

The dispatcher and the use-case map route on the semantic type. If the type of a pattern is not a MessageSemantics value, the pattern can match an activity but cannot send it to a handler.
SE-05-002 MUST A semantic type MUST have a use-case class in the use_case_map() mapping when, and only when, its SEMANTIC_REGISTRY entry is handled on receipt. An entry whose use_case_class is None is recognized but not handled.

Recognizing a semantic type does not imply a handler for it (ADR-0140 item 5). Several CASE_MANAGER shapes are written to the ledger but never handled when received (ADR-0152), and the registry still has to label them.
SE-05-005 MUST The dispatcher MUST report a received activity whose entry is recognized but not handled (SE-05-002) as "no use case found". The report is a REFUSED verdict, logged at INFO with the activity and actor IDs.

"No use case found" says the receiver does not handle the message, not that the message is invalid. No handler ran, so the verdict is not processed (UCORG-05-012).
Extends: SE-05-002
SE-05-006 MUST NOT For a recognized but unhandled activity (SE-05-002), the dispatcher MUST NOT raise, send a ProcessingFault or treat the activity as unrecognized (SE-04).

The message is not invalid, so it is not answered with a fault, and a raise would make it look like a bug. An unrecognized activity goes to the SE-04 path, which is for a shape that the registry does not know.
Extends: SE-05-002
SE-05-003 MUST All patterns MUST have unit test coverage

If no test uses a pattern, a change to the pattern classes or to the registry can stop the pattern from matching. The failure then shows only as messages that go to the wrong handler at run time. A test for each pattern finds the failure in CI.

Registry Order Enforcement

ID Priority Requirement Related
SE-06-001 MUST vultron/semantic_registry/ MUST run the guard _validate_registry_order() on SEMANTIC_REGISTRY at import time. The guard raises RegistryOrderError when a less-specific pattern precedes a more-specific one that it shadows.

find_matching_semantics() reads the registry in order and returns the first match. If a less specific pattern comes before a more specific one, the less specific pattern matches first and the specific pattern never matches. This defect is silent and shows only for the activities of the hidden pattern. Thus the check runs when the module is imported.
Verifies: SE-03-002
SE-06-002 MUST The registry order guard MUST raise RegistryOrderError, a named exception class in vultron/errors.py, not a generic ValueError or AssertionError.

With a dedicated exception, a test or a caller can tell an order defect from any other ValueError or failed assertion. The import failure also names its cause.
Refines: SE-06-001
SE-06-003 MUST The registry order guard MUST have a companion unit test that runs the guard on the current registry and fails if it raises RegistryOrderError.

The import-time guard protects the registry only when a process imports the module. A test that calls the guard on the current registry makes an order defect a named CI failure on the change that caused it.
Verifies: SE-03-002
Uses definition from: SE-06-001

Display Metadata

ID Priority Requirement Related
SE-07-001 MUST Every SemanticEntry in SEMANTIC_REGISTRY MUST carry a non-empty phrase: str field containing an active-voice format-string template suitable for human-readable event summaries (e.g. "{actor} submitted report {object}").

Each semantic type appears in event summaries that people read. When the phrase is on the registry entry, each type has one place for its words, and no separate display table can become different from the registry. Because the field is mandatory, a missing phrase is an error when the entry is built, not a gap that a person finds in a summary.
SE-07-002 MUST Phrase templates MUST use named slots drawn from the set {actor}, {object}, {target}, {context}, {origin}, {inner_object}.

A fixed set of slots lets a check find a phrase that uses an unknown slot. The render pipeline fills only {actor}, {object} and {target}. The other names are reserved, and SE-07-005 stops phrases from using them until the pipeline fills them.
Extends: SE-07-001
SE-07-007 MUST Each phrase template slot name MUST be a human-facing role identifier, not a Python field name from VultronEvent.

A slot name tells the role of a value in the sentence. Thus a phrase reads correctly to its author and stays correct when a VultronEvent field gets a new name.
Extends: SE-07-002
SE-07-003 MUST The SemanticEntry dataclass phrase field MUST have no default value so that omitting it is a construction-time TypeError, not a silent empty string.

Any default, including an empty string, lets an entry exist without a phrase. The summary is then blank. With no default, Python refuses to build the entry, so the gap shows when the module loads.
Implements: SE-07-001
SE-07-004 MUST A parametrized unit test MUST assert that every entry in SEMANTIC_REGISTRY has a non-empty phrase and that calling entry.phrase.format_map(d) with a defaultdict(lambda: "X") returns a non-empty string without raising a KeyError.

The dataclass rule of SE-07-003 finds a missing phrase. It does not find an empty phrase or an incorrect format string. A test that formats each phrase with all slots filled finds both before a summary is rendered.
Verifies: SE-07-001
SE-07-005 MUST A unit test MUST fail when a phrase in SEMANTIC_REGISTRY uses a slot outside the set the render pipeline fills today: {actor}, {object} and {target}. The set grows only when the pipeline fills another slot.

The SE-07-004 test fills each slot with a placeholder. Thus it cannot find a phrase that uses a slot that the render pipeline never fills. Such a phrase renders with a dangling dash. A check of the slot names against the filled set makes this a CI failure, not a defect that shows only in rendered output.
Verifies: SE-07-002
SE-07-006 MUST Companion behavioural tests MUST call event_phrase() and CaseTimelineEvent.summary with representative MessageSemantics values covering each distinct slot shape (actor-only, actor+object, actor+target) and assert: (1) no trailing "—" appears in the rendered output; (2) no un-substituted {slot} markers remain.

A phrase can use only allowed slot names (SE-07-005) and still render with a dangling dash. For example, this occurs when a target label does not resolve for one semantic type. Only a render of real summaries for each slot shape shows this problem.
Verifies: SE-07-002

Target-Field Discriminators

ID Priority Requirement Related
SE-08-001 MUST When two or more ActivityPattern entries share an activity_ type and an object_ type, the more-specific one MUST add a discriminator field (e.g. target_, context_). The field distinguishes it unambiguously from the less-specific pattern.

Without an additional discriminator, two patterns sharing the same verb and object type are indistinguishable; the first matching entry always wins.
SE-08-006 MUST For two ActivityPattern entries that SE-08-001 covers, the more-specific pattern MUST appear before the less-specific one in SEMANTIC_REGISTRY.

The registry returns the first match, so a less-specific pattern listed first shadows the more-specific one. _validate_registry_order() enforces the order at import time.
Refines: SE-03-002
Uses definition from: SE-08-001
SE-08-002 MUST A wire activity class whose semantic identity depends on a target-field discriminator MUST declare that target field as required (not optional) so that a sender omitting it produces a validation error rather than a silently misrouted activity.

Declaring the discriminator field as required ensures that any attempt to construct the activity without it fails fast at the sending side rather than reaching the receiver's registry as an ambiguous shape.
Derives from: SE-08-001
SE-08-004 MUST When an ActivityPattern uses target_ or origin_ as the sole field that distinguishes it from a less-specific competing pattern, strict=True MUST be set on that pattern so that a bare URI string in that field does NOT match the typed constraint.

A target_ or origin_ constraint accepts a bare URI by default (SE-01-007), and ActivityPattern.strict governs those two alone. Without strict=True, an unresolved target URI lets the more specific pattern match each competing shape, whatever the type of the target. Registry order is then the only protection against routing errors, and the discriminator has no effect (ADR-0039).
Refines: SE-08-001
Constrains: SE-01-007

Signing

Requirements for signing the activities an actor sends and verifying the activities it receives, using object-level proofs carried inside the activity (FEP-8b32) so that a proof stays checkable after a relay or a ledger commit. HTTP Signatures and production key handling are out of scope here (ENC-01, OX-10).

File ID: SIG

Verification and Refusal

ID Priority Requirement Related
SIG-03-003 MUST This codebase MUST verify a proof as its own ingress stage, after the body-size, media-type and JSON-shape checks and before parse_activity.

Verifying before the parser keeps a forged body away from expansion, validation and hydration, and keeps semantic extraction a mapping from verified AS2 to semantics that tests can exercise without keys. The cheap transport checks run first, so an oversized or malformed body is refused without a key fetch.
Implements: SIG-03-001
SIG-03-004 MUST This codebase MUST record on the ReceivedActivityRecord of a received activity, from the record's first save through its archive, each proof the inbox verified on the delivery: its author, its key id (verificationMethod) and the public key as fetched (publicKeyMultibase).

A receiver can then say which key a past message verified against, which key rotation needs (#1184), and a demo can check from the receiver's own store that it fetched the sender's key and verified with it, without re-deriving anything. The proofs travel with the received evidence, so intake writes them in the same save as the body and no crash between two writes can leave an archived record without them; a hold and a replay carry them from the record they rebuild from. For an Add(CaseLedgerEntry) the record names both the CASE_MANAGER's proof and the snapshot author's (SIG-04-002). A refusal leaves a receipt stub that keeps none (SIG-03-005).
Depends on: SIG-03-001
SIG-03-005 MUST NOT A receipt stub that a refusal leaves MUST NOT record verified proofs.

A refused message was not accepted, so its record must not read as verified; the stub keeps only who sent what, when and why it was refused (CLP-10-018).
Refines: SIG-03-004

Prototype Keys and the Signing Module

ID Priority Requirement Related
SIG-05-001 MUST In the prototype, each actor's key pair MUST be computed from a fixed seed tied to its actor id.

Tests, demos and documentation examples compare and show exact wire bodies, so their proofs must be the same on every run. A seeded key makes no security claim: anyone who knows the scheme can compute the private key, so a seeded key must never be deployed. Production key generation is ENC-01-001.
SIG-05-002 MUST NOT Verification MUST NOT derive a key from a seed.

A verifier that derives the author's key from the seed scheme verifies against a key the author never published, so it would admit a body from an actor whose profile it cannot read. Only a key's owner computes its key pair from its seed; every other actor gets the key from the owner's profile (SIG-02-001).
Refines: SIG-02-001
SIG-05-003 MUST Every proof this codebase creates or verifies, in tests too, MUST go through one shared signing module.

Canonicalization, key encoding and proof options must match exactly between signer and verifier, and each hand-rolled copy is a place for them to drift apart. One module, as the activity factories are for outbound construction, keeps one copy to test against published test vectors.
SIG-05-004 MUST An actor's outbox MUST refuse an activity whose actor names another actor, before signing or storing anything.

An actor holds only its own private key, so it signs only its own messages. Seeded keys (SIG-05-001) are guessable by design, so any code could compute any actor's key; the prototype keeps an actor from signing for another in code instead: only the owning actor's outbox calls the signer for that actor. The one other caller is the docs example renderer, which signs documentation examples, bodies no server sends, each only as its own actor (signing.sign_docs_example); test/architecture/test_seeded_signer_callers.py lists both callers. Real per-actor secret keys are ENC-01-001.
SIG-05-005 MUST An activity's actor MUST be the actor that signs it; when another actor initiated it, that initiator is carried in attributed_to, which is absent when the actor is the initiator.

A proof names its signer's key, and a receiver reads the author's key from the actor (SIG-02-001), so an actor that is not the signer is a claim the signer cannot back with its own key. The maintainer's rule: actor is always the signing actor; attributed_to is the actor who initiated the thing, set only when that initiator differs from the actor, since a copy of the actor is redundant. This supersedes ADR-0041 on one point: the CASE_MANAGER's genesis add_case_status_to_case entry names the CASE_MANAGER as actor, and the case owner that set the status stays in the status's attributed_to.

Spec Registry

Requirements for the structured spec registry: YAML spec files governed by Pydantic models, with linting, pytest integration, and context-generation tooling. The registry provides a single source of truth for spec IDs, prefixes, titles, and cross-reference validation.

File ID: SR

YAML File Format

ID Priority Requirement Related
SR-01-001 MUST Specifications MUST be maintained as YAML files in specs/ following the topic-file naming convention. Markdown spec files are not permitted.

One machine-readable format lets the registry loader, spec-lint and spec-dump validate and query every requirement. These tools cannot read a requirement in Markdown. Its ID, priority and links stay unchecked, and agents cannot load it by topic.
SR-01-002 MUST Each YAML file MUST have a top-level id field containing the file-level prefix string (e.g., "HP").

The file-level prefix is the start of every requirement ID in the file. When the file declares it one time, the linter can check each group ID and spec ID against it (SR-01-007, SR-01-013). An ID then tells a reader which file holds it.
SR-01-003 MUST A YAML spec file MUST NOT have a top-level version field.

A hand-maintained per-file version had no rule for when it changed and no check that it did, so it was a published claim nothing could falsify (MS-16-002). The release tag pins spec content and the requirement ID is the citation address (ADR-0106).
SR-01-014 MUST Each YAML spec file MUST have a title field and a description field.

The title names the topic in the docs and in spec-dump output. The description tells a reader what the topic covers. Without them, a reader cannot tell what a topic file is for.
Extends: SR-01-002
SR-01-004 MUST Each YAML spec file MUST contain a groups list.

Agents load requirements by group, and the spec backstop reports by group. Thus every requirement must be in a group. Tools cannot select or cite the requirements of a file with no groups.
SR-01-015 MUST Each group in a YAML spec file MUST have id, title and specs fields.

Tools select and cite a group by its ID, and the docs and the spec map show its title. The specs field holds the requirements of the group. A group without one of these fields cannot be selected, cited or shown.
Extends: SR-01-004
SR-01-005 MUST Each individual spec entry MUST have id, priority, statement, and rationale fields.

These four fields make an entry a usable requirement. They give an address, a binding strength, the rule and the reason for the rule. If one field is missing, readers cannot cite the entry, weigh it or understand it (MS-10-012).
SR-01-006 MUST Spec IDs MUST be globally unique across all loaded YAML files.

Tests, code comments, ADRs and other specs use the requirement ID to cite a requirement. A duplicate ID makes each of these citations ambiguous. Also, the registry index can hold only one of the two entries.
SR-01-007 MUST Group IDs within a file MUST match the file-level prefix (e.g., group HP-01 must live in file with id: HP).

The group ID prefix tells a reader which file holds a group. A group under the prefix of a different topic breaks that lookup, and navigation by ID becomes unreliable.
SR-01-008 SHOULD Each spec entry SHOULD include a testable boolean field (default true).

An untestable mark tells reviewers and the coverage tooling not to expect a test for the entry. The linter can then ask for behavioral steps instead (SR-04-005). An explicit default keeps entries without the field testable.
SR-01-009 MUST Spec entries MUST include a kind field from the SpecKind StrEnum; one of protocol, foundation, architecture, project, process.

The kind decides who must obey a requirement, which docs page shows it and which checks apply to it (ADR-0134). With a free-text value, a misspelled kind removes the requirement from every check that selects by kind.
SR-01-010 SHOULD Spec entries SHOULD include a scope field listing one or more Scope StrEnum values (prototype, production); default [production].

Scope lets an agent that works on the prototype skip requirements that apply only to production, and the reverse. A fixed enum stops a typo from creating a scope that no filter selects.
SR-01-011 SHOULD Spec entries SHOULD include a tags list using values from the SpecTag StrEnum vocabulary.

Tags let spec-dump --tag and the docs select requirements by subject across topics. A controlled vocabulary prevents near-duplicate tags that each select only part of one subject.
SR-01-012 MUST Each relationship in a spec entry MUST have a rel_type field and a spec_id field.

Tools cannot orient or resolve a relationship with no type or no target. The type gives the direction of the link (SR-13), and the target names the other requirement.
SR-01-016 SHOULD A spec entry SHOULD include a relationships list when a reader needs to trace it to another requirement.

The edges graph comes from the recorded relationships, so a reader can trace a change in one requirement to the requirements that it affects. A requirement with no recorded link is invisible to that trace.
SR-01-013 MUST Spec IDs within a group MUST match the group ID prefix (e.g., spec HP-01-001 must live in group with id: HP-01). This extends SR-01-007 to the spec level and ensures that the three-part ID (FILE-GROUP-SPEC) is internally consistent.

A reader who sees PD-03-001 expects to find it in group PD-03. If it is in a different group, navigation by ID and cross-references mislead the reader. When the spec ID matches its group ID, the three parts of the ID agree.
Extends: SR-01-007
See also: HP-01-001 — an example ID

Pydantic Schema

ID Priority Requirement Related
SR-02-001 MUST The vultron/metadata/specs/ module MUST define Pydantic models for all registry structures: SpecFile, SpecGroup, StatementSpec, BehavioralSpec, Relationship.

Typed models make the loader reject a malformed spec file when it parses the file, with an error that names the field. Every tool that reads the corpus then uses validated objects and does not check raw dictionaries again.
SR-02-002 MUST Fixed vocabularies MUST be implemented as StrEnum subclasses: RFC2119Priority, RelationType, SpecKind, Scope, SpecTag, AdrStatus.

A StrEnum gives each fixed vocabulary one definition. The schema validates against it and the tools import it. A misspelled value then fails at load time and does not silently create a new category.
SR-02-003 MUST RFC2119Priority MUST include at minimum: MUST, MUST_NOT, SHOULD, SHOULD_NOT, MAY.

The corpus uses these five RFC 2119 levels as binding strengths. The linter, the coverage guard and the backstop tier all branch on priority, so each level must be a valid value.
SR-02-004 MUST RelationType MUST include at minimum: implements, supersedes, extends, depends_on, conflicts, refines, derives_from, verifies, part_of, constrains, satisfies, uses_definition.

Each relationship type has a defined meaning and a defined upstream end (SR-13). The enum lets the schema reject an undefined type. Thus each link has a direction that the graph tooling can orient.
SR-02-005 MUST SpecKind MUST include all five portability tiers: protocol, foundation, architecture, project, process.

The kind records who must obey a requirement: every implementation, every implementation of an inherited standard, or only this codebase or process (ADR-0134). The checks that protect implementers and the docs routing both branch on the kind. Thus each of the five tiers must be a valid value, and no other value can be valid.
SR-02-006 MUST Scope MUST include: prototype, production.

Scope separates the obligations of the prototype from the obligations of a production implementation. An agent then loads only the requirements that its target must meet.
SR-02-007 MUST SpecTag MUST be a controlled vocabulary StrEnum, defined in vultron/metadata/specs/schema/vocabulary.py.

The schema module defines the tag vocabulary. This gives the linter (SR-04-006) and the selection tooling one list to check against, so a tag cannot come into use before the list declares it.
SR-02-008 MUST A SpecIdStr type alias MUST enforce the ID pattern ^[A-Z]{2,8}(-\d{2}(-\d{3}[a-z]?)?)?$ via Pydantic StringConstraints. The optional lowercase letter suffix (e.g., LST-05-002b) designates a sub-requirement split from a parent spec.

A fixed ID pattern makes each requirement, group and topic ID easy to recognize in prose, so tools can find and resolve citations (SR-04-008). The suffix lets a split requirement keep the address of its parent, so existing citations stay valid.
See also: LST-05-002b — an example of a sub-requirement ID
SR-02-009 MUST StatementSpec MUST have fields: id (SpecIdStr), priority (RFC2119Priority), kind (SpecKind, required), statement (non-empty str), rationale (non-empty str), and optional fields: testable, scope, tags, relationships, adr, lint_suppress.

These are the fields every consumer of the corpus reads, from spec-lint to spec-dump, so the schema is what guarantees each requirement has them. A required rationale keeps the reason for each rule next to the rule (MS-10-012).
Implements: MS-10-012
SR-02-010 MUST BehavioralSpec MUST extend StatementSpec with optional fields: preconditions, steps, postconditions.

Behavioral requirements need ordered steps, preconditions and postconditions, and a plain statement cannot hold them. An extension of StatementSpec keeps the shared fields, and the checks on them, the same for both forms.
SR-02-011 MUST The lint_suppress field on a spec MUST accept a list of LintWarningCode StrEnum values to suppress named linter warnings for that spec.

Some advisory warnings are wrong for a specific requirement. A typed suppression on the spec silences only that warning on that entry. It also records that the exception is deliberate, and a misspelled code fails validation.
SR-02-012 MUST SpecGroup MUST have the fields id (SpecIdStr), title and specs (a non-empty list), and the optional fields description, scope and trigger.

Every tool that reads a group needs its ID, its title and its requirements, so the schema makes sure that each group has them when it loads. The optional fields hold a description, a default scope and the trigger of a behavioral group.
SR-02-023 MUST NOT SpecGroup MUST NOT have a kind field.

Kind decides which checks apply to a requirement, so each item declares it where a reader can see it (SR-02-027). A kind on the group could give one item a wrong tier, and nobody would see the mismatch.
Extends: SR-02-012
SR-02-013 MUST SpecFile MUST have the fields id (str), title, description, scope (required) and groups (a non-empty list), and the optional field tags.

These fields identify and describe a topic file, and scope sets the default for the file. Every tool that reads a file needs them, so the schema makes sure that each file has them when it loads.
SR-02-024 MUST NOT SpecFile MUST NOT have a kind field.

Kind belongs on each item (SR-02-027). A kind on the file could give an item a wrong tier, and a reader of the item would not see it.
Extends: SR-02-013
SR-02-025 MUST NOT SpecFile MUST NOT declare a version field, so that its extra="forbid" configuration (SR-02-022) rejects a file that has one (SR-01-003).

No check confirms a file version (SR-01-003). When the schema declares no such field, the loader rejects a file that has one, and the rule needs no separate check.
Implements: SR-01-003
See also: SR-02-022 — the "so that" clause explains why the omission works; not declaring version needs nothing from SR-02-022
SR-02-014 MUST A scope value at SpecFile or SpecGroup level MUST serve as the default for the spec items under it.

A whole file usually has one scope, so a default prevents repetition.
SR-02-026 MAY An individual spec item MAY set its own scope, which overrides the default.

One requirement in a file can apply to a different target than the rest. An override on the item lets that requirement differ without a change to the file or group default (SR-02-014).
SR-02-027 MUST Every individual spec item MUST declare its own kind, which it does not inherit from its file or group.

A reader cannot see an inherited tier at the item. Such a tier can put a requirement under the wrong checks.
Refines: SR-01-009
SR-02-015 SHOULD Relationship SHOULD include an optional note field for free-text annotation of the relationship.

A relationship type tells how two requirements relate. It does not always tell which part of one requirement affects the other. A short note on the link records this, so neither statement must hold the explanation.
SR-02-016 SHOULD BehaviorStep SHOULD include fields: order (int), actor (str), action (str), and optional expected (str).

Ordered steps with a named actor let a reader or a conformance test follow a behavioral requirement one action at a time. The optional expected result tells what each step must produce.
SR-02-017 MUST The spec schema MUST define a TriggerType StrEnum enumerating the categories of behavioral trigger: message_received (a protocol message type), state_entered (an RM, EM, or CS state value), and scenario_start (a named demo or integration scenario). Enumerating kinds allows conformance tooling to classify trigger groups without parsing prose.

A behavioral group tells what starts it, and conformance tooling must read that information. A closed set of categories lets the tooling classify groups without parsing prose. It also makes a misspelled category a validation error, not a silent new category.
SR-02-018 MUST A Trigger object MUST carry a type: TriggerType field and a value string naming the specific message type (e.g. EP) or protocol state (e.g. RM.VALID) that activates the behavior; for scenario_start triggers value names the scenario (e.g. rv, rvv).

The type says what kind of event starts a behavior and the value names the specific event. Together they let conformance tooling match a trigger against a message or state without parsing prose.
SR-02-019 MUST A Precondition object MUST carry a description string that states the precondition in prose.

A prose description is for human readers. A reader cannot understand a precondition with no description.
SR-02-028 MAY A Precondition object MAY carry the typed state fields rm_state, em_state, role and cs_pattern. They hold a list of RM states, a list of EM states, a list of CVDRoles and a CS hypercube pattern string.

The optional typed state fields let conformance tooling test a precondition directly against the RM, EM, role and CS enums, without parsing the prose description.
SR-02-020 SHOULD A spec item SHOULD use the optional adr field (list of AdrIdStr, pattern ^ADR-\d{4}$) to record structured ADR provenance; the export emits each as a derives_from edge to the ADR ID so an amended ADR can be traced to its dependent specs via the edges graph, and the linter hard-errors on a dangling target.

Prose citations in rationale are invisible to the edges graph, so "which specs inherit this ADR's premise?" was not a mechanical query. The structured field closes that gap (MS-11-004). See ADR-0043.
SR-02-021 MUST StatementSpec MUST support these optional fields beyond the core set, and BehavioralSpec inherits them: verification, note, tracking_issue, verification_debt, references, exceptions, trigger and see_also. The verification field (NonEmptyStr) is a machine-executable or human-reviewable check that confirms the requirement is met. The note field (NonEmptyStr) is a correction notice or clarifying annotation. The tracking_issue field (str) holds the GitHub issue references that track planned implementation. The verification_debt field (#N) names the issue that owns verifying a MUST-tier requirement with no verification (MS-10-006). The references field (list[str]) holds file paths or URIs to supporting documents. The exceptions field (list[NonEmptyStr]) lists permitted exceptions to the rule that the requirement states. The trigger field (Trigger) is the activating event of a behavioral spec item. The see_also field (list[SeeAlso], empty by default) lists each requirement the statement cites that no relationship links, as a spec_id (SpecIdStr) and a reason (NonEmptyStr) saying why no relationship type fits.

Without these fields in the schema, the loader would reject (SR-02-022) or ignore annotations that requirements need. These annotations tell how a requirement is checked, who owns its missing check, its exceptions, its trigger, its supporting references and the citations it leaves unlinked. Typed fields let tooling validate each one. The list has no lifecycle field: a superseded requirement is removed and archived, not marked in place (MS-09-001).
Extends: SR-02-009
Uses definition from: MS-10-006
SR-02-022 MUST Every Pydantic model in vultron/metadata/specs/schema/models.py (Relationship, SeeAlso, Trigger, Precondition, BehaviorStep, Postcondition, StatementSpec, BehavioralSpec, SpecGroup, SpecFile) MUST declare model_config = ConfigDict(extra="forbid").

Without extra="forbid", the loader silently ignores an unrecognized YAML key. A misspelled field, or a field that the schema does not define, then loses its content with no error. A failure on unknown keys changes that silent data loss into a validation error, and each new field must go through the schema.
Constrains: SR-02-009

Registry Loader

ID Priority Requirement Related
SR-03-001 MUST The vultron/metadata/specs/ module MUST provide a load_registry(spec_dir) function that loads all *.yaml files from the given directory into a SpecRegistry.

One loader that reads the whole directory gives every consumer the same validated corpus. If each tool parsed the YAML in its own way, the tools could disagree about which requirements exist.
SR-03-002 MUST SpecRegistry MUST maintain an index of all specs by ID and enforce global uniqueness, raising ValueError on duplicate IDs.

Cross-references and citations resolve through the ID index. With a duplicate ID, the index keeps one entry and silently drops the other. An error at load time stops the corpus before any tool reads it.
SR-03-003 MUST SpecRegistry MUST provide a get(spec_id) method returning the Spec for a given ID, raising KeyError on unknown IDs.

Callers find a requirement by the ID that they have. An unknown ID is a caller error, such as a typo or a retired requirement. An exception makes the error visible, where an empty result hides it.
SR-03-004 MUST SpecRegistry MUST provide a validate_cross_references() method returning a list of error strings for any dangling relationship targets.

A relationship that names no existing requirement makes the graph show a dependency on nothing. Because the loader returns the dangling targets, the linter can report all of them as hard errors at one time (SR-04-002).
SR-03-005 MUST The loader MUST work regardless of the caller's working directory by accepting an explicit spec_dir path.

Pre-commit hooks, tests, CLI tools and agents run the loader, each from a different directory. An explicit path gives the same result from every location.
SR-03-006 SHOULD SpecRegistry SHOULD maintain a group index in addition to the spec index.

Agents load requirements by group, and the backstop reports by group. A group index lets those tools find a group by ID without a scan of every file.
SR-03-007 SHOULD The loader SHOULD provide a _find_repo_root() helper (mirroring the notes loader) for callers that do not supply an explicit path.

Callers that run in the repository must not have to calculate the spec directory. A shared root finder gives them the same default that every other metadata loader uses.
SR-03-008 MUST load_registry MUST attribute each file that fails its YAML parse or its SpecFile validation to the path of that file (MS-17-001).

load_registry backs every spec consumer — the linter, the pre-commit hook, spec-dump, the coverage report, the docs renderer, the pytest marker check — so an unattributed failure here is the one an author is most likely to meet. Attributing the parse alone would leave the more common fault unnamed: an invalid enum value (kind, priority, rel_type) is reported as a positional path into the parsed structure, which locates a requirement no better than a bare line number does.
Refines: MS-17-001
SR-03-010 MUST load_registry MUST get that file attribution from the shared helper that MS-17-003 names, not from a wrapper of its own.

One helper gives every metadata loader the same attribution format. A private wrapper in load_registry would drift from the other loaders, and an author would meet two error formats for one kind of fault.
Refines: MS-17-003
SR-03-009 MUST When more than one file in specs/ fails to load, load_registry MUST report every failing file in a single error, not only the first.

The loader rejects the corpus as a unit, so a caller told one reason at a time gains nothing from the round trip — the principle EH-07-001 states for validation boundaries. The linter that wraps this loader already collects and prints all of its own findings together, so stopping at the first file makes the loader the one part of the tool that reports less than it knows. The case that matters is a bulk spec edit breaking several files at once.
Refines: EH-07-001 — applies the report-every-violation rule to a file-walking loader
SR-03-011 MUST load_registry MUST carry each individual failure as structured data on the exception it raises, not only as a joined message.

A caller that acts on each failing file needs the failures one by one. Without structured data, it must parse the message text, which breaks when the message format changes.
Extends: SR-03-009

Linter

ID Priority Requirement Related
SR-04-001 MUST The vultron/metadata/specs/lint/ package MUST provide a lint(spec_dir) function that returns exit code 0 (clean) or 1 (errors found).

A fixed exit code lets the pre-commit hook and CI block a commit or a build on spec errors without parsing the linter's output.
SR-04-002 MUST The linter MUST report as hard errors: duplicate spec IDs, dangling relationship targets, group-ID/file-prefix mismatches, and invalid YAML structure.

Each of these faults makes the corpus wrong for every consumer. A duplicate ID makes citations ambiguous. A dangling target puts a link to nothing in the graph. A prefix mismatch breaks navigation by ID. Invalid structure stops the file from loading. None of these faults is safe to commit, so each must block the commit.
SR-04-003 MUST The linter MUST be invokable both as uv run spec-lint (console entry point) and as python -m vultron.metadata.specs.lint [spec_dir] (module invocation).

Agents and developers run the console entry point. The pre-commit hook runs the module form, which also works in environments where the entry point is not installed.
SR-04-009 MUST Both invocation forms of the spec linter MUST produce identical output for the same input.

Users and the pre-commit hook run different forms of the same check. If the outputs were different, one form could pass a corpus that the other form rejects.
Extends: SR-04-003
SR-04-010 MUST When spec_dir is omitted from the module invocation, the linter MUST default to specs/ relative to the current working directory.

The pre-commit hook and developers run the linter from the repository root, where specs/ is the corpus. A default directory keeps the usual command short. It does not hide which directory the linter checked.
Extends: SR-04-003
SR-04-004 MUST The linter MUST respect lint_suppress fields on individual specs when checking advisory warnings.

A suppression on a spec records a deliberate exception. If the linter ignored the suppression, authors would see the same accepted warning on every run and stop reading the warnings.
SR-04-005 SHOULD The linter SHOULD emit advisory warnings (non-blocking) for: specs with testable: false and no behavioral steps (suppressible via lint_suppress: [testable_without_steps]), rationale text exceeding 500 characters, and specs with no tags.

These patterns usually show a weak requirement, but they are sometimes correct. A warning thus starts a review and does not block the commit. A long rationale often contains a second requirement, or history that belongs in a different location.
SR-04-006 SHOULD The linter SHOULD check that tag values in spec entries are members of the SpecTag StrEnum vocabulary.

An undeclared tag selects nothing in spec-dump --tag or in the docs. Thus the requirement silently disappears from the subject of its tag.
SR-04-007 SHOULD The linter SHOULD check that scope at the spec level is not broader than the containing group or file scope.

A spec that claims a broader scope than its group or file contradicts the default that it must make narrower. A scope filter then includes or drops the spec when a reader does not expect it.
SR-04-008 MUST Every spec ID cited in a Python source file (production code, test file, or docstring/comment) MUST resolve to an entry in the spec registry; a citation of a non-existent spec ID is a hard error caught by the pre-commit lint gate (_check_phantom_spec_id_citations). Files under test/metadata/specs/ are exempted because they legitimately use synthetic fixture IDs.

A citation of a spec ID that does not exist looks like a settled requirement. The next reviewer must then disprove a mandate, not judge a design choice, so the citation misleads more than no citation. Where no requirement covers the behavior, a prose description is the correct record. Fixture IDs under test/metadata/specs/ are synthetic by design, so they are exempt.
SR-04-011 MUST NOT A module under vultron/ MUST NOT cite a requirement from the Testability topic (TB- prefix) as one it implements. Implements: citations are topic-scoped: resolving in the registry (SR-04-008) is necessary but not sufficient, and a resolving citation of a topic that governs tests is a defect, not traceability.

Each ID cited under vultron/ resolves to some requirement. Thus an existence check (SR-04-008) cannot find a citation of the wrong topic. The Testability topic governs tests, not modules. A module that names a TB- requirement as the requirement it implements points readers at the wrong rule, but it passes the existence check. A check scoped by topic finds that error.
Extends: SR-04-008

Pytest Integration

ID Priority Requirement Related
SR-05-001 MUST The project MUST register a spec pytest marker in conftest.py: @pytest.mark.spec("SR-01-001").

A registered marker lets each test name the requirement that it verifies. The coverage report and the coverage guard read this marker. The test configuration changes warnings into errors, so an unregistered marker causes a collection error for each test module that uses it.
See also: SR-01-001 — an example marker argument
SR-05-002 MUST pytest_collection_modifyitems MUST validate each spec marker value against the loaded SpecRegistry and emit UnknownSpecIdWarning (a UserWarning subclass, non-blocking per SR-05-007) for any unknown spec ID.

A marker that names a nonexistent requirement claims coverage for nothing, and a typo looks the same as a valid citation. Validation at collection time names the bad ID. The warning class is under vultron/metadata/specs/. Thus filterwarnings can select it by a stable path, and production code does not import pytest.
Depends on: SR-05-007
SR-05-003 SHOULD The pytest integration SHOULD load the registry once per session (not per test) to avoid I/O overhead.

The registry is the same for each test in a session. One load prevents a new parse of the whole corpus for each test.
SR-05-004 MUST A test that verifies a kind: protocol or kind: foundation requirement MUST carry @pytest.mark.spec("<ID>") naming that requirement.

Protocol- and foundation-kind requirements are conformance-critical. Without a marker, coverage for those requirements is unverifiable and the CI coverage guard (SR-05-005) cannot enforce it. foundation is covered with protocol because every rule an implementer must obey needs a test, whether Vultron defines it or inherits it (ADR-0134).
SR-05-008 SHOULD A test that verifies a requirement of any other kind SHOULD carry @pytest.mark.spec("<ID>") naming that requirement, so that coverage can be reported by spec ID.

A marker lets spec-coverage and the spec backstop link a test to the requirement it proves. For the lower-stakes kinds, a SHOULD keeps adoption opt-in, so no guard blocks a change for a missing marker.
SR-05-005 MUST CI MUST fail a pull request that adds an uncovered protocol or foundation requirement. An ID is added when no @pytest.mark.spec marker covers it at the head, but it was covered, or of neither kind, at the merge base. A requirement that leaves both kinds, or is retired, is not an addition.

A SHOULD-only marker rule produced near-zero adoption with no enforcement signal. foundation is guarded with protocol because every rule an implementer must obey needs a test (ADR-0134). Treating the two as one set means that a relabel from protocol to foundation is not a way around the guard.
SR-05-009 MUST When the coverage check of SR-05-005 fails a pull request, it MUST list each added uncovered ID.

The author must add a marker for each added ID. A failure that names no ID makes the author search the whole corpus for the cause.
Extends: SR-05-005
SR-05-010 MUST NOT The coverage check of SR-05-005 MUST NOT compare the uncovered set against a committed count.

Markers record coverage per item, so the check compares the uncovered set at the base with the set at the head, and commits no number. A one-sided ceiling collects silent slack, and a two-sided pin races every concurrent PR (notes/testing-pitfalls.md). spec-coverage prints the live untested total.
Extends: SR-05-005
SR-05-017 MUST spec-coverage MUST put each protocol and foundation requirement in one of four states and report the count of each. A marked test is held when a strict xfail is on it, with or without a condition, or when it cannot run, under an unconditional skip or an empty parameter list. A requirement is verified when at least one of its marked tests runs and none is held. It is partly met when at least one of its marked tests runs and at least one is held. It is xfail-only when each of its marked tests is held. It is untested when no @pytest.mark.spec marker names it. The coverage figure counts verified requirements only, so a partly-met requirement is left out of it.

A strict xfail states what main does not meet yet. Counted as covered, it makes the figure claim behavior no passing test shows, and hides the gap. A test that never runs shows no more, and an xfail condition cannot be read, so both hold. A held test beside a passing one still states a part main misses (#6075). The SR-05-005 guard reads only the untested set, because a held requirement has the marker SR-05-004 asks for.
Extends: SR-05-004
SR-05-018 MUST spec-coverage --json <PATH> MUST write the ID, kind, statement and state of each protocol and foundation requirement, and the count of each state of SR-05-017. Each entry also lists the test, the reason and the cited issue numbers of every hold of SR-05-017 on a test marked for the requirement, a skip's reason starting skip:, so a partly-met entry names the part that is held.

The known-gaps page of the Protocol Specification lists each requirement that a held test shows main does not fully meet, or that no test checks, with its statement and the issues that track it. A generator that reads this output needs no second scan of the tests, and the page cannot disagree with the coverage report.
Extends: SR-05-017
SR-05-006 MUST pytest_collection_modifyitems MUST handle three registry cases apart: no corpus, an unloadable corpus and an unexpected failure.

A gate that silently skips reports the same clean pass as a corpus with no unknown IDs. Thus one malformed spec file could disable marker validation for a whole session. Each case needs its own response, so the hook must tell them apart (SR-05-011, SR-05-012, SR-05-013).
Extends: SR-05-002 — SR-05-002 specifies the marker check; SR-05-006 specifies what happens when the registry it needs is unavailable
SR-05-011 MUST When specs/ is absent, or present with no spec files, pytest_collection_modifyitems MUST return silently.

With no corpus there is nothing to validate against and nothing is wrong, so a warning would be a false alarm.
Part of: SR-05-006
SR-05-012 MUST When specs/ exists but load_registry raises, pytest_collection_modifyitems MUST emit a SpecRegistryUnavailableWarning and return without validating markers. The warning names the spec directory, the underlying cause and the requirement whose gate is down.

The session must still run, because a malformed spec file must not block the tests that diagnose it. For this reason, the hook gives a warning that is non-blocking (SR-05-007) and does not raise. The warning keeps the disabled gate visible.
Part of: SR-05-006
SR-05-013 MUST NOT pytest_collection_modifyitems MUST NOT catch an exception type outside the documented load-failure set.

An unexpected exception type shows a bug in the loader, not a bad spec file. A catch-all handler would hide that bug (CS-23-001).
Part of: SR-05-006
SR-05-014 MUST The except clause of pytest_collection_modifyitems MUST name only the narrowest concrete types that an existing but unloadable corpus can raise (CS-23-002).

Narrow types are what keep an unexpected exception uncaught (SR-05-013). A blanket except Exception is a defect, because it catches every bug in the loader.
Implements: SR-05-013
Uses definition from: CS-23-002 — uses CS-23-002's narrowest-concrete-type notion for the pytest collection hook, which sits outside CS-23-002's vultron/ scope, so it is no case of it
SR-05-007 MUST Every warning that the pytest integration relies on being non-blocking MUST have a matching always:: entry in the filterwarnings list of pyproject.toml.

The "error" entry of filterwarnings turns every other warning into a failure. Without an exemption, a non-blocking warning would change into a collection abort.
SR-05-015 MUST Each such always:: entry MUST come after the "error" entry in filterwarnings.

pytest applies ini filterwarnings in list order through warnings.filterwarnings(), which puts each filter at the front of the list. Thus a later entry wins, and an always:: entry before "error" has no effect. This order is the reverse of what readers expect.
Extends: SR-05-007
SR-05-016 MUST A test MUST verify each such entry by emitting the warning in a sub-session under the project's real filter list. A check of the position of the entry alone does not verify it.

Only a behavioral check under the real filter list can find an error in the order. pytest.warns and catch_warnings replace the ini filters, and a position assertion passes when the behavior is broken.
Verifies: SR-05-015

Pre-commit Hook

ID Priority Requirement Related
SR-06-001 MUST A spec-lint pre-commit hook MUST be defined that fires on any staged change to a specs/*.yaml file.

Without a hook, only CI or the next agent that loads the corpus finds a spec error. The linter runs on each staged spec change, so it finds the error before the commit.
SR-06-002 MUST The hook MUST run python -m vultron.metadata.specs.lint specs/ and block the commit on exit code 1.

A hook that only reports lets a broken corpus go into a commit. A block on exit code 1 keeps each commit loadable by the tools that depend on it.
SR-06-003 MUST The hook MUST be configured with pass_filenames: false so the full registry is always validated, not just the changed file.

Cross-references, ID uniqueness and relationship loops go across files. A lint of only the changed file can miss an error that the change causes in a different file, such as a removed ID that a different file still cites.

Context Generation Tool

ID Priority Requirement Related
SR-07-001 MUST The vultron/metadata/specs/ module MUST provide a context generation tool that accepts a SpecRegistry and produces output for agent consumption.

The full corpus is much larger than the context of an agent. A tool that renders a requested part of the registry gives agents validated content in a form that they can load.
SR-07-002 MUST The tool MUST support a markdown renderer that regenerates a .md view of a spec file from its YAML source.

Reviewers and readers of the published documentation read prose, not YAML. When the Markdown comes again from the YAML, the readable view stays the same as the authoritative source.
SR-07-003 MUST The tool MUST support a JSON exporter that serializes the full registry or individual spec files to JSON.

Other tools and agents parse JSON reliably. An export from the validated registry gives them the same requirements that spec-lint checked, not a separate parse of the YAML.
SR-07-004 SHOULD The markdown renderer SHOULD produce output compatible with the existing meta-specifications.md style guide.

A rendered view that follows the documented spec style looks like the rest of the documentation. A reader then does not have to learn a second layout.
SR-07-005 SHOULD The JSON exporter SHOULD support filtering by kind, scope, tags, or priority to allow agents to request only relevant subsets.

Most tasks need only a small part of the corpus. A filter by attribute lets an agent load the requirements that apply to its work, without the rest.
SR-07-006 SHOULD The spec-dump CLI SHOULD support a --kind flag that takes comma-separated SpecKind values. The flag filters the LLM-optimized JSON output to the matching requirements.

Different work must obey different tiers. Protocol work needs protocol and foundation, and tooling work needs project. A kind filter selects a tier directly.
SR-07-018 MUST When --kind names an unknown kind, spec-dump MUST exit with code 2 and print an error that lists the valid values.

An empty result would tell the reader that no requirements apply. An error that shows the valid choices tells the reader that the value was wrong.
SR-07-007 MUST The spec-dump CLI MUST support an --index flag that prints a plain-text spec map instead of JSON: one line per topic (ID Title (N reqs)) followed by one indented line per group (GROUP-ID group title (N)), counting only requirements that match the other flags.

The unfiltered JSON dump is several megabytes, far larger than an agent context window. A map of topics and groups lets an agent choose what to load before loading it.
SR-07-008 MUST The spec-dump CLI MUST support the comma-separated selectors --topic, --group and --ids, and a --deps flag that adds every selected requirement's transitive dependencies.

Targeted loads replace the full dump.
SR-07-019 MUST spec-dump MUST combine the --topic, --group and --ids selectors as a union.

A union lets one call load a primary topic together with specific groups or IDs from other topics.
Extends: SR-07-008
SR-07-009 SHOULD The spec-dump CLI SHOULD expose --tag (comma-separated; all tags must match), --scope, and --priority flags that narrow the selected requirements, alongside --kind.

These attributes go across topics. A filter on them lets an agent take only the binding or in-scope requirements from a selection.
SR-07-010 MUST The spec-dump CLI MUST support a --cross-cutting flag that adds the topics in the CROSS_CUTTING_TOPICS constant of vultron.metadata.specs to the selection.

Several skills load the cross-cutting topics with every task. One flag gives every skill the same list.
SR-07-020 MUST The CROSS_CUTTING_TOPICS constant MUST be the single definition of the cross-cutting topic list.

Copies of the list that each skill keeps by hand become different over time. One definition behind the flag keeps them the same.
Extends: SR-07-010
SR-07-011 MUST The spec-dump CLI MUST exit with code 2 and write an error to stderr that names the offending values when a --topic, --group, --ids, --tag, --scope, or --priority value is unknown, or when a flag is given without its value.

An empty result for a mistyped ID looks the same as "no requirements apply", which is the wrong conclusion for an agent to draw silently.
SR-07-012 SHOULD The spec-dump CLI SHOULD support a --slim flag that reduces each requirement to id, priority, statement, and note (when set), keeps only relationship edges whose both ends are in the output.

note stays because it records which side an obligation binds; dropping it leads to requirements implemented at the wrong layer.
SR-07-013 SHOULD When spec-dump runs without --index and without any selector or filter flag, it SHOULD still print the full JSON dump to stdout.

spec-audit needs the full corpus.
SR-07-021 SHOULD On such a run, spec-dump SHOULD write one warning line to stderr that states the output size and suggests --index and the selector flags.

An agent that runs the bare command by habit needs to learn that the output does not fit in its context.
Extends: SR-07-013
SR-07-014 MUST The spec-dump CLI MUST support a --text flag that renders the selected requirements as indented text. The text holds a topic header, a group header, then one ID PRIORITY statement line per requirement.

The JSON dump is a single line, so an agent that prints a load of any size sees a truncated prefix of one unreadable token; observed agent runs piped every load through jq to read it at all. One line per requirement truncates gracefully and costs fewer bytes than the JSON.
SR-07-022 MUST spec-dump MUST reject --text without a selector, with exit status 2.

A --text run without a selector would print the whole corpus as text. Requiring a selector keeps --text from reproducing the full-dump wall.
Extends: SR-07-014
SR-07-015 MUST The selection that --text requires MUST be a set selector (--topic, --group, --ids, --adr or --cross-cutting) that names at least one value.

Only a set selector bounds the output to the requirements that an agent asked for. Without one, --text prints the wall that SR-07-022 exists to prevent.
Refines: SR-07-022
SR-07-023 MUST NOT An attribute filter such as --kind or --priority MUST NOT satisfy the selection that --text requires.

Attribute filters keep whole topics, so counting one as a selection let --text --kind protocol print 285 KB. That is the wall the selector requirement exists to prevent.
Refines: SR-07-015
SR-07-024 MUST spec-dump MUST exit with status 2 when a set selector names no values, such as --topic "".

An empty list means "select nothing" to the exporter but "no selection" to the size guard, so --topic "" printed an empty dump under a warning about an unfiltered one. The empty list is a typo, and the tool should say so.
SR-07-016 MUST The glossary-index entry point MUST render one line per ## section of docs/reference/glossary.md. The line carries the line range and the terms of the section, and the aliases to avoid for each term.

The glossary is ~82 KB, most of it definitions a given task never touches; the index is ~12 KB and carries the naming guard, which is the part every session needs. Line ranges are what let deepen-context read one section instead of the file.
SR-07-025 MUST glossary-index MUST attribute each term table to the section whose line range contains it, not to a section with a matching heading.

Two sections can share a heading. Matching on heading text instead of position gave two such sections each other's terms.
Refines: SR-07-016
SR-07-017 MUST The spec-dump CLI MUST support an --adr set selector, a comma-separated list of ADR-NNNN ids. It selects every requirement whose adr: field names one of those ids, as a union with the other selectors.

deepen-context routes through decision records by reading the adr: edge backwards instead of reading a record body (ADR-0127, MS-11-008), and agents do not read raw spec YAML.
Extends: SR-07-008
SR-07-026 MUST spec-dump MUST exit with status 2, naming the value, when an --adr value is malformed or names no record. A value is malformed when it is not an ADR-NNNN id. The record search covers the docs/adr/ beside the spec directory, archived records included.

A typo in a record ID would otherwise give an empty selection, which reads as "this record governs nothing". The error names the value, so the agent can correct it.
Extends: SR-07-017
SR-07-027 MUST spec-dump MUST write a note to stderr for each named record that no requirement cites in adr:. The note names the record and points at its prose citations under specs/ and notes/.

Some live records are reached only by prose citation, so an empty selection for one of them would read as "this record governs nothing". The note says where its rule is stated instead.
Extends: SR-07-017
SR-07-028 MUST When spec-dump writes such a note, it MUST still print the selection.

The note adds to the output and replaces nothing. A run that also names cited records must still give their requirements.
Extends: SR-07-027

Docs Renderer Kind Routing

ID Priority Requirement Related
SR-09-001 MUST The render_for_kind(kind, registry) function MUST route each spec item of kind architecture, project, or process to the docs page that matches its kind field.

Each item declares its own kind, with no inheritance from group or file, so a requirement renders on the page for its own tier. No group or file value can put it on the wrong page.
SR-09-004 MUST The docs renderer MUST render each protocol or foundation spec item in the Requirements Catalog of the Protocol Specification (DF-12-001), not on a kind page.

Protocol and foundation items apply to every implementation, so they render in the catalog of the Protocol Specification, with the normative specification text (ADR-0147).
Extends: SR-09-001
Uses definition from: DF-12-001
SR-09-002 MUST A group with items of mixed kinds MUST appear on each docs page that matches the kind of at least one of its items. The Requirements Catalog's protocol and foundation pages count as pages for this rule (DF-12-001).

A mixed group holds items for more than one page, so each of those pages needs the group context. The protocol and foundation pages of the catalog use the same rule, so a mixed group also splits there (ADR-0147).
Uses definition from: DF-12-001
SR-09-005 MUST On each docs page, the renderer MUST omit the items of a group whose kind does not match that page. The Requirements Catalog's protocol and foundation pages count as pages for this rule (DF-12-001).

If a page rendered the whole group everywhere the group appears, items would repeat and some items would show the wrong portability tier. When each page hides the items of other kinds, the page stays accurate.
Extends: SR-09-002
Uses definition from: DF-12-001
SR-09-003 MUST The spec linter MUST emit a hard error (exit 1) when any spec item is missing a kind field. There is no inheritance fallback; kind is required on every individual spec item.

Mandatory per-item kind prevents the category-page placement errors and agent confusion that arose from implicit inheritance. Failing fast at lint time ensures the registry stays clean.

Migration

ID Priority Requirement Related
SR-08-001 MUST All existing specs/*.md files MUST be migrated to specs/*.yaml using a lossless conversion that preserves all requirement text, IDs, and relationships.

Code, tests, ADRs and other specs cite requirement IDs, wording and relationships. A lossy conversion would break those citations or silently change what a requirement says.
SR-08-003 MUST YAML files in specs/ are the sole authoritative source for project specifications. No other format or location holds normative spec content.

Two normative sources for one requirement can disagree, and a reader cannot tell which source applies. One authoritative location lets the linter and the tools use the YAML as the complete corpus.
SR-08-004 MUST specs/README.md MUST be retained as Markdown; it is documentation, not a requirement file.

specs/README.md tells how the corpus is organized and how to use it. It holds no requirements, so the YAML-only rule (SR-08-003) does not apply to it. Readers who look through specs/ still need an entry point that humans can read.
SR-08-005 MUST All in-project skills, prompts, and agent instructions that reference specs/*.md files by path or extension MUST be updated to use specs/*.yaml paths or the context-generation tool output before the migration is considered complete.

A skill or prompt that points at a Markdown spec path sends agents to a file that does not hold the requirements. The agents then work without the requirements that they must load, and nothing reports the problem.
SR-08-006 MUST NOT The original specs/*.md requirement files MUST NOT be deleted until the YAML files have passed the spec linter with zero errors.

Until the YAML loaded correctly, the Markdown files were the only copy of the requirements. An earlier deletion could lose requirement text that the conversion dropped.
SR-08-008 MUST NOT The original specs/*.md requirement files MUST NOT be deleted until all agent and skill references have been updated to use specs/*.yaml paths.

If the Markdown files are deleted while a skill still points at them, that skill loads nothing. No error shows that the requirements are missing.
Uses definition from: SR-08-005
SR-08-007 SHOULD A migration script SHOULD be provided to convert a single specs/*.md file to the YAML format as a starting point; manual review and cleanup is expected.

Manual conversion of files is slow and causes errors. A script makes a correct first version, and the expected manual review finds what the script gets wrong.

Story Traceability

ID Priority Requirement Related
SR-11-001 MUST StatementSpec MUST support an optional stories field that holds a non-empty list of StoryIdStr values (pattern ^story_\d{4}_\d{3}$). The values name the user stories that motivated the requirement.

Bidirectional traceability between requirements and stakeholder user stories is a NASA systems engineering criterion. Without back-references in spec files, tracing "which stakeholder need does this requirement serve?" requires consulting the manually-maintained docs/reference/user_stories/traceability.md matrix, which drifts as specs evolve. Embedding story references in the spec files makes the spec the authoritative source and enables automated change-impact analysis.
SR-11-005 MUST The schema MUST apply the _nonempty_if_present validator to the stories field.

An empty stories: list would claim a trace to user stories and name none. The validator rejects that list at load time, so a present field always names a story.
Implements: SR-11-001
SR-11-002 MUST Each story ID in a stories: field MUST match the pattern ^story_\d{4}_\d{3}$, such as story_2022_001.

A fixed pattern lets the schema reject a malformed or misspelled story ID at load time. Thus each story reference resolves against the story catalog.
Refines: SR-11-001
SR-11-006 MUST The StoryIdStr type in vultron/metadata/specs/schema/ids.py MUST enforce that pattern through Pydantic StringConstraints.

A constrained type checks the pattern wherever a story ID is validated. A check in each tool would be repeated, and one copy could differ from the others.
Implements: SR-11-002

Spec Selection Backstop

ID Priority Requirement Related
SR-12-001 MUST By default, spec-backstop MUST treat as changed each .py file that is untracked or that differs from the merge base of --base and HEAD. The diff runs to the working tree, and --base defaults to origin/main.

Agents choose which requirements to load by judgment. A check computed from the diff catches under-selection without trusting that judgment. The working tree is included because an agent runs the check before it commits.
SR-12-014 MUST When --paths is given, spec-backstop MUST use the named files as the changed set, each treated as fully changed.

Before any code exists, an agent names the files that the work will touch. The check then runs on those files, while a missed requirement is still cheap to act on.
Extends: SR-12-001
SR-12-002 MUST spec-backstop MUST treat as a changed symbol each top-level function, class, or assignment whose line span, decorators included, intersects a diff hunk.

Symbol-level matching is much narrower than module-level matching. A module such as vultron/core/behaviors/bridge/ is imported by dozens of test files, but only the tests that import the edited names govern the edit.
SR-12-015 MUST spec-backstop MUST count a changed method as a change to its class.

Tests import a class, not its methods. A method change attributed to its class reaches the tests that import that class.
Refines: SR-12-002
SR-12-016 MUST spec-backstop MUST count every top-level symbol of a fully changed file as changed.

A file named with --paths, or a new file, has no hunks to intersect. Every symbol it defines is part of the change.
Refines: SR-12-002
SR-12-003 MUST spec-backstop MUST report as required, in its MUST tier, the spec groups that each of four signals links to the change. The first signal is the @pytest.mark.spec IDs in test files that import a changed symbol by name. The second is those IDs in mirror-path test files of a changed module. The third is those IDs in the changed parts of changed test files. The fourth is the requirements whose statement names a changed module's path or dotted name, or a long changed symbol, as a whole word. A changed symbol is long when it has six or more characters or is in CamelCase.

Each signal is a deterministic link between the change and a requirement. Directory prefixes and short symbol names are excluded because they match too many unrelated statements.
SR-12-004 SHOULD spec-backstop SHOULD report as advisory, in its INFO tier, the spec groups of test files that import a changed module by any name.

A module import is weak evidence. Listing it without enforcing it gives the agent a place to look without adding false alarms.
SR-12-017 SHOULD spec-backstop SHOULD omit from the INFO tier every group that is already in the MUST tier.

A group listed in both tiers would be read twice and could look advisory. The MUST tier already asks the agent to resolve it.
Extends: SR-12-004
SR-12-005 MUST spec-backstop MUST report each hit at the spec-group level, listing the requirement IDs that matched and the deduplicated evidence for them.

Agents load specs by topic and group, so a group-level report maps directly onto the manifest. The evidence lets the agent judge a hit instead of loading it blindly.
SR-12-018 MUST When --json is given, spec-backstop MUST emit the same report as JSON.

A calling script needs the report in a form that it can parse without reading the text layout.
Extends: SR-12-005
SR-12-006 MUST When --manifest names a file, or - for stdin, spec-backstop MUST read the topic, group and requirement IDs on its Loaded lines as loaded. It reads those IDs on its Considered, skipped lines as dismissed.

A dismissal with a reason is an explicit judgment and satisfies the check, so the tool must tell it apart from a load.
SR-12-019 MUST spec-backstop MUST exit with code 1 and list every MUST-tier group that the manifest does not resolve. A group is resolved when it or its topic is loaded, when it is dismissed, or when each of its matched requirement IDs is listed.

A group that the manifest does not mention at all is the under-selection the check exists to catch. The exit code lets a caller gate on it.
Uses definition from: SR-12-006
SR-12-007 MUST spec-backstop MUST write to stderr a note naming each changed source file that produced no MUST-tier signal.

An empty MUST tier for a file with no tests and no spec mentions is not evidence that no requirement applies. The note stops the agent from reading silence as coverage.
SR-12-008 MUST spec-backstop MUST exit with code 2 and write an error to stderr when it runs outside a git repository in diff mode, when the --base ref cannot be resolved, or when the manifest file cannot be read.

Exit code 1 means unresolved groups. A setup failure must not look like either a pass or a finding.
SR-12-009 MUST spec-backstop MUST move to the INFO tier the symbol-import hits of a changed symbol that more than --hub-threshold test files import. The threshold defaults to HUB_THRESHOLD, which is 10.

A hub such as BTBridge is imported by most behaviour tests, so symbol-import matching on it puts about 75 groups in MUST and the check stops discriminating.
Supersedes: SR-12-003
SR-12-020 MUST spec-backstop MUST keep the mirror-path and statement-mention hits of a hub symbol in the MUST tier.

A mirror-path test or a statement that names the symbol is a direct link to the change, however many files import the symbol. Only the import signal loses its meaning for a hub.
Refines: SR-12-003
SR-12-021 MUST spec-backstop MUST print each hub symbol with its importer count in the report.

Naming the hubs keeps the demotion visible, so an agent does not read the shorter list as coverage.
Extends: SR-12-009
SR-12-010 MUST spec-backstop MUST tier a group by the priority of the requirements that matched. A group whose matched requirements are all SHOULD, SHOULD_NOT or MAY goes to the INFO tier. Thus only a MUST or MUST_NOT requirement can leave the manifest unresolved.

An unresolved MUST group blocks the build, so the blocking set has to be requirements that themselves bind. A SHOULD-only group such as TRIG-05 forced a spec load with no obligation behind it.
Supersedes: SR-12-003
SR-12-011 MUST spec-backstop MUST move to the INFO tier the marker-derived hits of a test file whose spec markers span more than MONOLITH_GROUP_SPAN requirement groups.

A 17-group catch-all suite put 13 unrelated groups in MUST from one import. The median test file here spans 2 groups and the 90th percentile spans 6, so a threshold of 8 demotes only genuine whole-subsystem suites.
Supersedes: SR-12-003
SR-12-022 MUST spec-backstop MUST exclude the module-level boilerplate names logger and log, and their case variants, from the changed-symbol set.

logger is assigned in nearly every module, so it matched every requirement that mentions logger.info.
Supersedes: SR-12-002
SR-12-023 MUST When a diff contains no Python source, spec-backstop MUST report that a passing exit status is not coverage.

A docs-only diff exits 0 with no signal at all, which reads as a pass.
SR-12-012 MUST spec-backstop MUST pin the diff prefixes it parses by passing --src-prefix=a/ and --dst-prefix=b/ to git diff.

diff.mnemonicPrefix renames the prefixes, and every file then parses as unchanged. Measured, 6 changed files and 4 MUST groups became 0 and 0, exit 0 against any manifest.
Implements: SR-12-001
SR-12-024 MUST spec-backstop MUST accept a --paths entry that does not exist yet.

--paths names files the work will create, so a missing file cannot be a setup error.
Refines: SR-12-014
SR-12-025 MUST spec-backstop MUST report each changed path that it did not analyse because the path is outside vultron/ and test/.

A path outside both trees was dropped without a word, so its change read as covered.
SR-12-013 MUST A free-text reason after an em-dash in a manifest entry MUST run to the next ;, or to a sentence-ending . before a fresh ID.

The asymmetry decides the rule: over-reading a reason costs a false alarm the author can answer, while under-reading it silently drops the check.
Refines: SR-12-006
SR-12-026 MUST NOT A , inside such a reason MUST NOT start a new manifest entry.

Splitting a reason on every comma read prose as a dismissal: BT-01 — irrelevant, CM-02 covers it marked CM-02 dismissed, so an unresolved MUST group for CM-02 passed the gate.
Derives from: SR-12-013

Relationship Type Semantics and Direction

What each rel_type asserts, which end of a relationship is upstream, which end records it, and the spec-lint checks that keep the requirements graph free of loops so that "what does a change to this requirement affect?" has one answer.

ID Priority Requirement Related
SR-13-014 MUST spec-lint MUST report as a hard error each loop in the requirements graph whose arcs run from each relationship's downstream end to its upstream end. A loop is a strongly connected component of more than one requirement, or a requirement whose relationships name itself.

"What does a change to this requirement affect?" walks the graph against its arrows, and a loop makes every member upstream of every other. Orienting by upstream end, not by which end recorded the link, also catches a constrains recorded backwards, which the recorded edges alone hide.
Extends: SR-04-002
SR-13-020 MUST Each loop error that spec-lint reports MUST name every requirement in the loop.

An author must break the loop at one of its links. An error that names only some members hides the links that the author must check.
Extends: SR-13-014
SR-13-015 MUST spec-lint MUST report as a hard error each pair of requirements whose relationships name each other, naming both requirements and every relationship between them.

A pair recorded at both ends is not always a loop: A refines B with B constrains A points both arcs the same way. The pair check enforces SR-13-012 directly.
Verifies: SR-13-012
Extends: SR-04-002
SR-13-016 MUST The RelationType docstring MUST list each member's definition from one table in vultron/metadata/specs/schema/vocabulary.py that also records each member's upstream end.

The definitions are needed both by readers of the specs and by the code that orients the graph. One table keeps the two from drifting, where a second prose copy would not.
Uses definition from: SR-02-004
SR-13-021 MUST A test MUST fail when that table and the definitions SR-13-001 through SR-13-011 and SR-13-017 differ.

Checking the table against the requirements keeps the code's definitions the same as the ones the specs state.
Extends: SR-13-016
See also: SR-13-001 — an end of the range the test compares against; the duty to have the test does not change when a definition does
See also: SR-13-011 — an end of the range the test compares against; the duty to have the test does not change when a definition does
See also: SR-13-017 — the last definition the test compares against; the duty to have the test does not change when a definition does
SR-13-023 MUST spec-lint MUST report as a hard error, naming both requirements, each requirement ID that a statement writes out with no relationship to the citing requirement and no entry in its see_also.

Without the check, a new citation lands unjudged and the audit has to be done again. Naming both requirements tells the author which pair to judge.
Verifies: SR-13-022
Extends: SR-04-002
SR-13-024 MUST spec-lint MUST report as a hard error each see_also entry whose ID the statement does not write out, that a relationship already links, that names no requirement or the citing requirement itself, or that repeats an earlier entry.

A see_also reason that outlives its citation, or that sits beside a link, tells the reader something false about the two requirements. Checking each entry keeps the list as current as the statement it explains.
Extends: SR-13-023

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

State Enum Design

ID Priority Requirement Related
SM-01-001 MUST RM, EM, VF, D and PEC MUST each be a Python StrEnum, and PXA an Enum of three-flag PxaState tuples, serialized by member name.

A StrEnum member is equal to its string value and serializes as that string. A state that is stored or sent as a bare label (SM-08-001, SM-08-003) thus reads back as the same member, and code can compare it with a received string without a conversion step. A PXA state is three flags, and code reads each flag off the member's tuple value. Its member name, such as pxa, is still a bare label, so PxaDimension writes that name and reads it back to the same member.
SM-01-002 SHOULD State enums SHOULD provide both a full descriptive name and a short single-character alias for each state

The protocol documentation names states by single-letter codes, such as R for Received and A for Accepted. Code is easier to read with full names. When both names are aliases of one member, a code in the documentation and a name in the code always mean the same state.
SM-01-003 MUST State enum values are the authoritative definition of valid states

Guards and transition checks must agree on which states exist. If a guard uses a raw string or an integer, a misspelled or renamed state can pass without an error. When every check refers to the enum, the enum is the one place that defines a valid state.

State Machine Definitions

ID Priority Requirement Related
SM-02-001 SHOULD Each state axis SHOULD have a corresponding create_*_machine() factory function that produces a transitions library Machine instance for the axis

A factory builds the machine for an axis from its transition list in one place. Tests, diagrams and exports that call the factory then get the same machine, and they do not each build a different copy of it.
SM-02-002 MUST NOT create_*_machine() factory functions MUST NOT be called for runtime state changes in production use-case or handler code

A transitions Machine keeps its own current state in memory. The real state of a case is in the stored status records (SM-05-001, SM-06-002). A machine used for a runtime change would hold a second copy of that state, which can differ from the stored value and is lost when the process stops. Runtime changes are checked against the transition list instead.
Extends: SM-02-001
SM-02-003 SHOULD Trigger names for transitions library machines SHOULD be defined as a companion StrEnum (e.g., RM_Trigger) using auto() so that trigger strings remain stable and are not inlined as string literals scattered across the codebase

A trigger name that is a string literal at each call site is not checked by a type checker, so a misspelled trigger fails only when the code runs. A companion StrEnum gives each trigger one definition that tools can check and that does not change when code moves.

Transition Definitions

ID Priority Requirement Related
SM-03-001 SHOULD Each state transition SHOULD be expressed as a typed TransitionBase subclass with trigger, source, and dest fields typed to the appropriate enums

A typed transition model checks its trigger, source and destination against the enums when the module loads. A misspelled state or trigger in the transition list thus fails at import, not when a participant first tries that move.
SM-03-002 SHOULD Transition definitions SHOULD be stored as a module-level list in the same module that defines the state enum

When the transition list is next to the state enum, a reader sees the states and their allowed moves in one module. The transition checks and the machine factory then read the same list.
SM-03-003 MUST Every valid (source → dest) pair that the protocol describes MUST have a corresponding transition entry.

The transition checks, such as is_valid_rm_transition, admit only the pairs that are in the list. A valid pair that is missing from the list thus causes the implementation to refuse a move that the protocol permits.

State History

ID Priority Requirement Related
SM-05-002 MUST A participant's current status MUST be the last ParticipantStatus appended to its history, the baseline its transition guards judge an update against. A case's current status is likewise the last CaseStatus appended (CM-29-001).

A history holds more than one entry, and each reader needs the same current value from it. A participant's statuses are appended only after the transition guards accept them, so append order is the order this actor accepted them in. A received status carries the sender's time, which can be earlier than a status already held (ADR-0103), so a timestamp rule could make an older status current and judge the next update against the wrong baseline. CM-29-001 gives the case history's reasons.
SM-05-003 MUST Each status MUST carry its author's time: the sender's published and updated, as sent or absent, when received, and now_utc() at creation when authored here. The trusted time of a received event is its ledger entry's commit stamp (CM-02-009), not a field on the status.

A status's published and updated say when its author made it. A receiver that wrote its own clock there would replace that claim with its arrival time, and two replicas of one status would then disagree. A receiver that filled an omitted time would claim a time that the sender never sent (ADR-0103). The time that this actor can trust for ordering is the commit stamp on the ledger entry (CLP-14-002), so the status needs no second trusted field.
Uses definition from: CM-02-009

In-Memory (Transient) State

ID Priority Requirement Related
SM-06-001 SHOULD Transient state used only during a single request (e.g., for tracking report status during validation processing) SHOULD be clearly separated from persisted state

State that lasts for only one request is lost when the request ends. If it is mixed with persisted state, code can save it by mistake or read it as if it were stored. A clear separation shows which values survive the request.
SM-06-002 MUST RM state for reports MUST be persisted as participant-level state in CaseParticipant records. In-memory transient RM state is not permitted.

In-memory state is lost when the process stops, and each process has its own copy. RM state in CaseParticipant records survives a restart and gives one auditable RM history for each participant, from report receipt to closure (ADR-0013).

State Subsets and Guards

ID Priority Requirement Related
SM-07-001 SHOULD Commonly used groups of states that define validity zones for transitions SHOULD be defined as module-level constants (tuples or frozensets) in the same module as the state enum

Guards often test the same group of states, such as the RM states that can close. When the group has one definition next to the enum, every guard tests the same set. A set that is copied into each guard can change in one place and not in the others.
SM-07-002 MUST State subset constants MUST be derived from enum values, not raw strings, to prevent silent mismatches when enum values change

A raw string in a state set matches the enum value only while the two spellings agree. If the enum value changes, the raw string matches no state, and the guard gives a wrong result with no error. A set made from enum members changes with the enum.

Wire and DataLayer Compatibility

ID Priority Requirement Related
SM-08-003 MUST In this implementation, the DataLayer MUST store state values as the same bare label strings the wire uses (SM-08-001), never as integers or as qualified forms such as RM.RECEIVED.

A stored row is read back by other processes and after restarts, so a state stored as an integer or a qualified form would read back as a different value, or as none, wherever the enum's order or module path changes.
Uses definition from: SM-08-001
SM-08-002 MUST When deserializing state values from the DataLayer or from wire payloads, the receiving Pydantic model MUST declare the state field with the StrEnum type so that Pydantic coerces the incoming string to the correct enum member

A field typed as str accepts any string, so a state that is not valid reaches core as an ordinary string. A field typed with the StrEnum makes Pydantic convert the value to the enum member and refuse an unknown value during validation (ADR-0032).

CS Forced Transitions and Reachable States

ID Priority Requirement Related
SM-09-001 MUST This codebase MUST enforce two forced (ephemeral) CS transitions at validation time: pX → PX and vP → VP. In pX → PX, exploit public forces public aware. In vP → VP, public aware forces vendor aware.

These transitions are protocol-correctness invariants, not optional normalizations. A CS state of pXa (exploit public, public unaware) is semantically impossible — the exploit being public implies the vulnerability is public. Implementors MUST use is_ephemeral_cs_state() and required_next_cs_events() from vultron/core/states/cs_invariants/ to enforce this rule at the persistence boundary, for the states an actor holds for itself and the case status the CASE_MANAGER commits (SM-09-003). A received claim is stored as sent (RSH-09-010). This requirement governs the persistence boundary only; CSB-17-003 and CSB-17-005 cover trajectory validation, where an ephemeral state is a legal prefix terminus.
Implements: CSB-17-003 — SM-09-003 governs the persistence boundary: an actor's own state or conclusion carrying vP or pX MUST be promoted to the forced form before it is stored, and a received claim is stored as received. CSB-17-003 governs trajectory validation, where the same two conditions are modelled as ephemeral states with exactly one legal successor. The two are consistent because they apply at different boundaries: no actor persists a vP or pX state as its own, but such a state is still a legal intermediate point in a replayed history, and CSB-17-004 therefore permits a history prefix to end in one.
SM-09-003 MUST This codebase MUST record each CS state that an actor holds or concludes for itself in its forced form (SM-09-001). A state that holds pX or vP is promoted before it is persisted. A record of a status received from another actor is not the receiver's own state: it is stored exactly as received (RSH-09-010). When the CASE_MANAGER adopts a received status, the case's CaseStatus it commits is its own conclusion, in the forced form.

An actor's own pX or vP state is one that no participant can be in, so promotion keeps every state an actor asserts for itself reachable. A received status is the sender's claim about its own view. If the receiver rewrote it, the record would show a status that nobody sent (ADR-0107). The case's CaseStatus, which the CASE_MANAGER arbitrates and every replica copies (CLP-07-013), is the case-level fact, so case-level reads use it and never the claim.
Implements: SM-09-001
See also: RSH-09-010 — the received-status rule this one defers to: it says what a received claim's record holds, and no SR-13 relationship fits that split

Generated Statecharts

ID Priority Requirement Related
SM-11-001 MUST Each protocol state machine (RM, VF, D, PXA, EM and PEC) MUST have a committed statechart in Sismic's YAML format that is generated from that machine's transition table in the core layer.

The transition tables are what an actor's own moves and every embargo register step are held to. A generated chart gives the occasions and the documentation one representation to refer to, with no second owner of the protocol's state behaviour (ADR-0128). The embargo register's per-entry lifecycle is bookkeeping beneath EM that no message names, so it has no chart.
SM-11-002 MUST A generated statechart MUST chart every transition of its machine's table and no other transition.

A chart that omits the EM register-dependent moves would describe less than the table the embargo register is held to, which is the drift the charts exist to remove.
Extends: SM-11-001
SM-11-003 MUST Two chart transitions that share a source state and a trigger MUST be told apart by a named condition: an identifier declared in the core layer beside the machine's transition table and defined in prose in the protocol documentation.

Whether an EM rejection or acceptance leaves Proposed or Revise for a given state depends on whether another proposal stays open (ADR-0130), so the EM table has two moves for one trigger from one state. Declaring the name beside the table keeps the core layer the one owner, so the generator adds no fact. An identifier keeps the chart free of any implementation language, and a later SCXML export can map it to a cond naming an externally defined predicate.
Extends: SM-11-002
SM-11-004 MUST Every generated statechart MUST load in Sismic without error.

The generator writes Sismic's schema by convention. Only loading the file proves it; Sismic is a dev-only dependency for that test, and transitions stays the runtime library (SM-02-001).
Extends: SM-11-001
SM-11-005 MUST Each state diagram of a single charted machine on the process-model and protocol specification pages MUST be a committed mermaid fragment generated from that machine's statechart.

The hand-written diagrams are held to the tables by no check. Labels name the messages whose occasions declare each transition (MSM-08-012), so the diagrams are joined from the charts and the occasions.
Depends on: SM-11-001

Status Dimension Objects

Normative requirements for per-machine dimension objects decomposed from CaseStatus and ParticipantStatus. Each independent state machine (EM, PXA, RM, VF, D) is represented by a lightweight Pydantic BaseModel that holds its state enum and owns immutable transition() validation and guard methods.

File ID: SDO

Dimension Object Base Contract

ID Priority Requirement Related
SDO-01-001 MUST Each status dimension (EM, PXA, RM, VF, D) MUST be implemented as a lightweight Pydantic BaseModel subclass (not a CoreObject subclass) that holds exactly one state enum field and, except EM, owns the transition validation and guard methods for that machine. EM has no transitions of its own, and EmDimension holds the copy of the EM state that the case derives from its embargo register (ADR-0122).

Dimension objects are embedded value objects; they have no independent identity and do not require CORE_VOCABULARY registration or AS2 id_. See ADR-0036.
SDO-01-002 MUST NOT Dimension objects MUST NOT be registered in CORE_VOCABULARY or given an id_ field.

They are always embedded in CaseStatus or ParticipantStatus, which already carries identity. Independent registration would create unnecessary schema complexity. See ADR-0036.
SDO-01-003 MUST The dimension objects MUST be named: EmDimension (EM state), PxaDimension (CS_pxa state), RmDimension (RM state), VfDimension (CS_vf state, the vendor path) and DDimension (CS_d state, the deployer path). Participant embargo consent is not a status dimension: it is a per-embargo row set on the participant (CM-18-001, ADR-0122).

The "Dimension" suffix avoids collision with the existing VfState, DState and PxaState NamedTuples in vultron/core/states/cs/states.py. ADR-0075 split the former vendor-fix-deployed machine into the VF and D machines, so each has its own dimension object. See ADR-0036.
See also: CM-18-001 — context for the reader
SDO-01-004 MUST A dimension object MUST serialize to its bare state value, not to a one-key {"state": ...} mapping.

A dimension holds one data field, state; the rest is behaviour, and behaviour does not serialize. The mapping form would put a container on the wire whose only content is the thing it contains. This is what lets the core class emit the payload the wire class emitted, so the wire form is unchanged.
Extends: SDO-01-001
Refines: ARCH-25-005
SDO-01-005 MUST A dimension object MUST accept on input both its bare state value and a one-key {"state": ...} mapping.

Accepting both forms keeps callers that construct {"state": ...} working, and it keeps rows stored in either form readable.
Extends: SDO-01-004

transition() Contract

ID Priority Requirement Related
SDO-02-001 MUST Each dimension object except EmDimension MUST implement a transition(trigger) method that validates the trigger against the current state, applies the state machine rules, and returns a NEW dimension object with the updated state. EmDimension has none, because EM changes only by an embargo register step (ADR-0122).

Immutable transitions are consistent with Pydantic's design philosophy and with the append-only status history model. Callers replace the embedded field rather than mutating the existing object. See ADR-0036.
SDO-02-002 MUST A dimension object's transition() MUST raise a descriptive exception (VultronInvalidStateTransitionError or a subclass) when the trigger is not valid for the current state.

Fail-fast at the boundary; never return None or silently no-op on an invalid transition. See ADR-0032 and ARCH-15-001.
SDO-02-003 MUST NOT A dimension object's transition() MUST NOT mutate self.

Mutation of embedded Pydantic models is fragile and inconsistent with the append-only history model. See ADR-0036.
SDO-02-006 MUST A caller of a dimension object's transition() MUST use the returned dimension object as the updated state.

transition() leaves the original unchanged (SDO-02-003), so a caller that keeps the original object keeps the old state and loses the step.
SDO-02-004 MUST Dimension objects MUST reject construction with an invalid (current_state → target_state) transition at construction time, regardless of call site. A same-state write (target == current) is always permitted; a None target (preserve current) requires no validation.

Constructing a dimension object by target state bypasses the transition() validation contract established in SDO-02-001/SDO-02-002, so without a check at construction any call site that builds a snapshot this way, BT write nodes among them (BTND-10-001), can record a step the state machine forbids. A same-state write changes nothing, so it needs no check.
Extends: SDO-02-002 — Extends the transition() contract to direct-construction call sites
Implements: CSB-16-001
Implements: CSB-16-002
SDO-02-005 MUST The SDO-02-004 transition-rejection invariant MUST be enforced via Pydantic field or model validators so that validation occurs at model construction time, not via caller-side pre-checks.

A caller-side pre-check protects only the call sites that remember to make it. A validator on the model runs on every construction, including call sites added later, so no path can build a dimension object at an illegal target state.
Implements: SDO-02-004

CaseStatus and ParticipantStatus Field Shape

ID Priority Requirement Related
SDO-03-001 MUST CaseStatus MUST replace its flat enum fields (em_state: EM, pxa_state: CS_pxa) with embedded dimension object fields: em: EmDimension and pxa: PxaDimension.

Flat enum fields provide no transition validation or guard methods. Dimension objects make illegal transitions unrepresentable. See ADR-0036.
SDO-03-002 MUST ParticipantStatus MUST carry its participant-level state as embedded dimension object fields, not flat enum fields: an always-present rm: RmDimension, an optional vf: VfDimension (present for a VENDOR participant) and an optional d: DDimension (present for a DEPLOYER participant); a participant with both roles carries both. It carries no embargo consent (CM-18-001, ADR-0122).

Same rationale as SDO-03-001. VF and D are separate machines (ADR-0075), and each applies only to the role that owns it, so each is optional. See ADR-0036.
See also: CM-18-001 — context for the reader
SDO-03-003 MUST NOT The old flat enum fields (em_state, pxa_state, rm_state, vfd_state, em_consent_state) MUST NOT be retained as aliases or shim properties after the migration is complete.

Keeping both representations creates an extended half-migrated state and perpetuates the flat-enum problem. See ADR-0036.
SDO-03-004 MUST After the dimension-object migration, a CaseStatus or ParticipantStatus MUST round-trip through the DataLayer.

DataLayer round-trip compatibility is a binding design constraint per LST-05-003 and ADR-0033. A dimension field serializes as its bare state value and rehydrates via Pydantic model_validate (SDO-01-004, ADR-0211). See ADR-0036.
SDO-03-007 MUST The DataLayer MUST rehydrate a persisted CaseStatus or ParticipantStatus record to the dimension-object shape.

A record stored before the migration must still read back as the new shape. Input accepts both the bare value and the one-key mapping (SDO-01-005), so a stored row in either shape rehydrates.
Extends: SDO-03-004
SDO-03-005 MUST When this codebase removes a flat-field migration shim from CaseStatus or ParticipantStatus, it MUST NOT leave a retired flat key silently discardable on in-process or stored data. An inbound key follows the parse-edge rule instead: a near miss is refused (MV-11-002), any other key is set aside and reported (MV-11-003). The retired flat keys are rm_state, vf_state, d_state, vfd_state/vfdState, em_consent_state/emConsentState, em_state and pxa_state.

Pydantic v2 ignores unknown keys by default. With extra="ignore", a flat rm_state key would be silently discarded and rm.state would default to RM.START — a whole RM ladder lost with no error, which is the defect class of issue #2232 and a violation of ARCH-15-001/ARCH-15-002.
Constrains: SDO-03-003 — SDO-03-003 requires the shims to go; this requirement constrains how they are removed safely.
See also: MV-11-002 — context for the reader
See also: MV-11-003 — context for the reader
SDO-03-008 MUST CaseStatus and ParticipantStatus MUST refuse a retired flat key through the extra="forbid" model configuration that ARCH-12-003 requires of every core-branch type.

extra="forbid" is strictly stronger than a reject-guard that enumerates the known flat keys. It also catches typos and stale keys from an older schema, needs no per-class maintenance, and covers every registered core type rather than the two named here. Because Pydantic itself raises, the failure surfaces as a pydantic ValidationError rather than VultronValidationError.
Implements: SDO-03-005
Refines: ARCH-12-003 — ARCH-12-003 supplies the extra="forbid" configuration that replaces the per-class reject-guard.
SDO-03-009 MUST NOT This codebase MUST NOT add or keep a per-class model_validator(mode="before") reject-guard on CaseStatus or ParticipantStatus to refuse a retired flat key.

extra="forbid" already refuses the key (SDO-03-008), so a reject-guard only duplicates it and needs upkeep for each key. No wire→core recovery is attempted: there is no backstop (ADR-0082), and extra="forbid" is the guard (ADR-0211).
Extends: SDO-03-008
SDO-03-006 MUST A CaseStatus's EM copy MUST be immutable once the status is constructed.

EM is derived from the case's embargo register (ADR-0122); the status holds only a stamped copy. An in-place write makes the copy disagree with the register, and EMB-18-001 forbade it with no enforcement. Freezing fails every write path at runtime, including dynamic ones a source ratchet would miss, while the case's copy-based stamp still works. EmDimension has no transitions, so freezing removes no behavior (#4321).
Implements: EMB-18-001
SDO-03-010 MUST This codebase MUST make EmDimension a frozen model and CaseStatus.em a frozen field. Then assigning status.em, status.em.state or any flat EM spelling raises.

Freezing fails every write path at runtime, including dynamic ones a source ratchet would miss. EmDimension has no transitions, so freezing removes no behavior (#4321).
Implements: SDO-03-006

Wire Projection and Migration Scope

ID Priority Requirement Related
SDO-04-002 MUST All call sites in vultron/ and test/ (excluding vultron/bt/) that access the old flat enum fields (em_state, pxa_state, rm_state, vfd_state, em_consent_state) MUST be migrated to use the new dimension object accessors (e.g. .em.state, .rm.state) in the same implementation.

A partial migration leaves the codebase in an incoherent state with two representations active simultaneously. See ADR-0036.
SDO-04-003 MUST NOT The vultron/bt/ legacy simulation layer MUST NOT be migrated to dimension objects as part of this implementation.

vultron/bt/ uses the custom BT engine and is not part of the active prototype. It accesses RM/EM/PEC state enums directly and is explicitly excluded from prototype handler work per codebase conventions. See notes/codebase-structure.md.

Structured Logging Requirements

Logging requirements for the Vultron API, covering log format, correlation IDs, log levels, state transition logging, error context, and authorization and data-access audit records.

File ID: SL

Log Format

ID Priority Requirement Related
SL-01-001 MUST All log entries MUST include timestamp field in ISO 8601 format

An operator puts logs from several actors and services together to follow one case. An ISO 8601 timestamp with its offset names one instant in every log, whatever the time zone or locale of the host that wrote it.
SL-01-002 MUST All log entries MUST include level field (DEBUG, INFO, WARNING, ERROR, CRITICAL)

Operators filter logs by severity to find failures among a large volume of normal output. A level field on each entry makes that filter possible without a parse of the message text.
SL-01-003 MUST All log entries MUST include component field (module or function name)

The component field tells a reader which module wrote an entry. Without it, a reader must guess from the message text where to look in the code.
SL-01-004 MUST All log entries MUST include message field (human-readable text)

A person reads the message to learn what happened. Structured fields serve tools, but they do not tell a person the event in words.
SL-01-005 MUST The message argument of a log call MUST be a literal template whose values are passed as lazy positional arguments (logger.info("Actor %s engaged case %s", actor_id, case_id)), never a string formatted before the call by an f-string, str.format(), %-formatting, or concatenation.

Python's logging keeps the template (msg) and its values (args) apart on the record and formats them only when a handler emits. That split gives every recurring event one stable template to group, grep, and assert on; it defers rendering the arguments (str() and % conversion) until a record is known to be emitted; and it keeps a fault raised while rendering an argument inside the logging machinery instead of in the caller. Only rendering is deferred: an argument expression is still evaluated at the call, so a value produced by a call (a tree dump, a logfmt() render) still needs an isEnabledFor guard, while a guard that only avoided f-string formatting is removed. A pre-formatted string discards all three properties. Structured record fields (SL-02) are a separate mechanism and are not an alternative way to interpolate values into the message. Enforced by ruff rules G001-G004 (ADR-0094).
Extends: SL-01-004

Correlation IDs

ID Priority Requirement Related
SL-02-001 MUST Log entries MUST include activity_id field when activity is available

One received activity can cause log entries in many modules. An activity_id field lets a reader collect all entries for one activity, across modules and actors, with one filter.
SL-02-002 MUST Log entries MUST include actor_id field when actor is available

One server can host several actors, and their log entries mix in one stream. An actor_id field lets a reader separate the entries for each actor and follow what one actor did.
SL-02-003 MUST A correlation field (activity_id, actor_id) MUST reach the log record as a record attribute populated from ambient context that is established once at the processing boundary (inbox receipt of an activity, BT execution on behalf of an actor) and applied to every record by a logging.Filter, not supplied per call through extra=.

A per-call extra= must repeat the same value at every log site, and a site that omits it writes a record with no correlation. Context that is set once at the processing boundary and copied by a filter reaches every record written inside that boundary, also from code that knows nothing about correlation. The formatter decides how to show the fields: a text formatter can print them next to the message, and a structured formatter can write them as separate fields. No call site changes.
Implements: SL-02-001
Implements: SL-02-002
SL-02-004 MUST Interpolating an identifier into the message text MUST NOT be treated as satisfying SL-02-001 or SL-02-002; the message may name the identifier for readability, but the record attribute is the carrier those requirements refer to.

An identifier embedded in free text cannot be filtered, grouped, or asserted on without parsing the message, and the narrative INFO template (SL-04-006) names the actor for the human reader, not for correlation. Making the record attribute the only thing that counts keeps the two audiences from being conflated: the message serves the person reading the transcript, the attribute serves the tooling.
Refines: SL-02-001
Refines: SL-02-002

Log Level Semantics

ID Priority Requirement Related
SL-03-001 MUST Log levels MUST follow standard Python logging severity semantics: DEBUG for diagnostic detail, INFO for normal protocol operations, WARNING for recoverable anomalies, ERROR for failures requiring attention, and CRITICAL for system-threatening failures.

Operators set a log level to choose how much output they see. When each level means the same thing in every module, a WARNING threshold shows all recoverable problems and failures and hides normal operation. The standard Python meanings are the ones that every library in the process already uses.
SL-03-002 MUST The received runner MUST log exactly one WARNING line per delivery it reports REFUSED, with the reported reason, the activity id and the sender's id.

Only the runner reads the delivery's verdict, so only it knows whether a FAILURE refused anything. A node guessed it from the tree's shape, and each guess that went wrong logged a refusal for a sender the tree admitted or a delivery it reported SKIPPED (#5460, #5786, #5845, #5903, #5917). One line per refused delivery, written where the verdict is read, is the outcome a reader and a log matcher can trust, and the reason in it is the one the handler reports, so the two cannot drift (#6477).
Refines: SL-03-001
SL-03-003 MUST A behaviour-tree node whose FAILURE records a reason the handler may report as a refusal MUST log that reason at DEBUG.

A node cannot know whether its FAILURE is the delivery's verdict: a later Selector arm may admit the sender, and the verdict reading may report the run SKIPPED. Its line is diagnostic detail under SL-03-001; the refusal, when there is one, is the runner's line (SL-03-002). At DEBUG the facts stay for whoever debugs the run (#6477). A fault (a malformed activity, an unreadable ledger entry, a store error) is not a refusal reason and keeps its SL-03-001 level.
Refines: SL-03-001
SL-03-004 MUST A log line other than the received runner's refusal line MUST NOT carry the REFUSED (IDs) group that a refusal reason ends with.

REFUSED is the token a reader greps and the demo tests match to assert that no sender was refused. A node, the bridge's run summary or the receipt-stub line that repeats a reason with its group makes one refusal look like several, and a reason from an overruled arm look like a refusal. Stripping the group from every other line keeps the token to the verdict, so the matcher can key on the runner's one line per refused delivery (#5460, #6477).
Extends: SL-03-002

State Transition Logging

ID Priority Requirement Related
SL-04-001 MUST All state transitions MUST be logged at INFO level

State transitions tell the protocol story. A reader of an actor's INFO log must see each change of RM, EM, CS and participant state, without the volume of DEBUG detail. The default log level is INFO, so a transition logged only at DEBUG does not appear.
SL-04-002 MUST State transition logs MUST include before state

A transition shows a change only when the reader knows the start state. With the before state in the entry, a reader can see an unexpected transition without a search through the earlier log.
SL-04-003 MUST State transition logs MUST include after state

The after state is the result of the transition. A reader needs it to know the actor's current state without a read of the code that ran.
SL-04-004 MUST State transition logs MUST include triggering event (activity type + semantic)

A reader who sees a state change must know what caused it. The activity type and its semantic tell the reader which message caused the transition, so the reader can find the same message in the sender's log.
SL-04-005 SHOULD Demo scripts and stepwise workflows SHOULD use structured, consistent lifecycle logs

People run the demos to learn the protocol. Lifecycle lines with one consistent form let a reader follow the demo steps in order and see at once which step or check failed.
SL-04-006 SHOULD State transition log messages SHOULD follow the narrative template "Actor '' '' ( → )" so that reading an actor's INFO log tells the complete protocol story without requiring DEBUG. See notes/structured-logging.md for the full template inventory.

One sentence form lets a reader scan an actor's INFO log as a story: who did what to which object, and how the state changed. Tests can also find a transition with one pattern. With this form, the INFO log is enough to follow the protocol, and a reader does not need DEBUG output.
SL-04-007 MUST This codebase MUST log each infrastructure line at DEBUG or lower, never at INFO. Infrastructure lines are persistence store, save and update lines, BT scaffolding and HTTP handler parsing echoes. Pipeline completion repeats, FSM internal callbacks and per-recipient sync queue entries are infrastructure lines too.

Infrastructure lines, such as a store write or a BT setup step, repeat for each activity and say nothing about the protocol. At INFO they hide the state transitions that the INFO log exists to show (SL-04-001). At DEBUG they stay available for diagnosis.

Error Context

ID Priority Requirement Related
SL-05-001 SHOULD ERROR level logs SHOULD include exception type and message

The exception type and message tell an operator what failed without a debugger. An ERROR entry with no exception detail tells only that something failed.
SL-05-002 SHOULD ERROR level logs SHOULD include stack trace for unexpected exceptions

An unexpected exception is a defect, and the stack trace shows where in the code it started. Without the trace, a person must reproduce the fault to find it. An expected error that the code handles does not need a trace.
SL-05-003 SHOULD ERROR level logs SHOULD include original activity ID if available

When an ERROR entry names the activity, an operator can find the activity that caused the failure and read its other log entries. Without the ID, the operator must match the failure to an activity by time alone.

Authorization Logging

ID Priority Requirement Related
SL-06-001 SHOULD Authorization decisions SHOULD be logged with decision (allowed/denied)

A security review must show which actions the system allowed or denied. A log entry for each authorization decision gives that record, and a series of denials can show misuse while it occurs.
SL-06-002 SHOULD Authorization logs SHOULD include actor performing action

An authorization record must name who asked. Without the actor, a reviewer cannot tell which actor made the request.
SL-06-003 SHOULD Authorization logs SHOULD include resource being accessed

A reviewer must know what the actor tried to access. The resource tells which case, report or other object the decision protected.
SL-06-004 SHOULD Authorization logs SHOULD include denial reason if denied

A denial with no reason is hard to tell apart from a configuration fault. The reason lets an operator see whether the system worked as designed or a rule needs a change.

Data Access Logging

ID Priority Requirement Related
SL-07-001 SHOULD Sensitive data operations SHOULD log operation type (CREATE, READ, UPDATE, DELETE)

A record of sensitive data operations must show what each operation did. A read of embargoed vulnerability data has a different risk from an update or a delete, so the entry must give the operation type.
SL-07-002 SHOULD Data access logs SHOULD include resource type and ID

The resource type and ID tell a reviewer which record an operation touched. The reviewer can then find all operations on one case or report.
SL-07-003 SHOULD Data access logs SHOULD include actor performing operation

An audit record must name who did each operation. A reviewer can then hold each actor responsible for its access to sensitive data.

Performance Metrics

ID Priority Requirement Related
SL-08-001 MAY System MAY log performance metrics at DEBUG level

Timing data helps find slow steps, but at INFO it hides the protocol story (SL-04-001). At DEBUG the data is available when an operator asks for it.

Sync Behavior Trees

Requirements for behavior-tree-based implementation of sync log entry protocol flows. Covers three BTs: AddLogEntryReceivedBT (received-side hash-chain validation with case-actor vs non-case-actor branching), RejectLogEntryReceivedBT (replication state update and replay), and CommitLogEntryBT (append, persist, fan-out).

File ID: SBT

General Sync BT Requirements

ID Priority Requirement Related
SBT-01-001 MUST This codebase MUST implement every sync log entry protocol flow as a behavior tree, not as procedural use-case code.

Ledger replication is protocol behavior. It decides what a replica accepts, when the replica rejects an entry, and which entries the CASE_MANAGER sends again. In a tree, each of these decisions is a named node, with a trace and its own tests. Procedural code in a use case hides these decisions from the behavior layer (BT-06-001).
Refines: BT-06-001 — Protocol-significant behavior in BTs
Refines: BT-06-006 — Protocol actions MUST NOT be outside BT
SBT-01-006 MUST This codebase MUST replace the procedural sync logic in received/sync/ and triggers/sync.py with BT invocations through BTBridge.

These two modules hold the sync use cases. A use case that runs its tree through BTBridge keeps its sync decisions in the tree, where SBT-01-001 puts them.
Implements: SBT-01-001
SBT-01-002 MUST Sync BTs MUST be organized as separate trees, each corresponding to a single message-type use case: (1) AddLogEntryReceivedBT, (2) RejectLogEntryReceivedBT, (3) CommitLogEntryBT, (4) ReadLedgerReceivedBT, the CASE_MANAGER's answer to a position statement (SYNC-17-002), and (5) the participant's StateLedgerPositions tree that sends one (SYNC-17-007). This preserves the one-message-type-per-use-case pattern.

Each sync message has its own guards and effects. With one tree for each message type, each flow is small enough to read and test alone. Also, the dispatcher continues to route each semantic type to exactly one use case and one tree.
See also: SYNC-17-002 — context for the reader
See also: SYNC-17-007 — context for the reader
SBT-01-003 MUST Sync BT nodes MUST reside in vultron/core/behaviors/sync/, with node definitions in its nodes/ package and each tree composition function in its own module.

A fixed location for sync nodes and trees lets a developer find an existing node before the developer writes a new one. When nodes are separate from tree composition, several trees can reuse one node and do not import each other.
SBT-01-004 MUST BTBridge.setup_tree() MUST inject driven ports, such as SyncActivityPort and DataLayer, into BT nodes through the blackboard.

A node that gets its own ports binds core logic to one adapter, and the node cannot run against a test double. When the bridge injects ports through the blackboard, nodes use only the port protocols. Then each test or deployment can choose the adapters.
SBT-01-007 MUST NOT A BT node MUST NOT construct or acquire a driven port itself.

A node that builds or looks up its own port binds core logic to one adapter, and the node cannot run against a test double. Taking every port from the blackboard (SBT-01-004) keeps the choice of adapter with the caller.
Extends: SBT-01-004
SBT-01-005 MUST NOT Core use cases MUST NOT call trigger functions for sync operations. Triggers are external API entry points, for example for demo puppeteering, and core work flows through BTs.

Triggers are entry points for an outside caller. When a core use case calls a trigger, it runs a second, nested path around the tree that it belongs to. This puts its guards, its commit order and its trace in two places.

AddLogEntryReceivedBT

ID Priority Requirement Related
SBT-02-001 MUST AddLogEntryReceivedBT MUST include an explicit branch that decides whether the receiving actor is the CASE_MANAGER for the case that the log entry names.

The CASE_MANAGER and a participant do different things with an announced entry. The CASE_MANAGER holds the canonical ledger and only checks its own echo. A participant validates the entry and stores it in its replica. The tree must know which of the two it is before it acts.
SBT-02-011 MUST In AddLogEntryReceivedBT, the CASE_MANAGER path and the participant path MUST be distinct subtrees.

Separate subtrees keep the two rule sets apart, so a change to the participant's validation cannot alter the CASE_MANAGER's echo check.
Extends: SBT-02-001
SBT-02-002 MUST The non-case-actor (participant) path MUST validate the received log entry's hash chain before persisting.

If a replica stores an entry without a check of its chain, it can accept a forged, reordered or gapped entry. Then the replica drifts from the canonical ledger. Validation before persistence keeps each stored replica a true prefix of the canonical ledger of the CASE_MANAGER.
Implements: SYNC-03-001 — Reject on hash-chain divergence
SBT-02-007 MUST In the non-case-actor path, prev_log_hash MUST match the receiver's local chain tail hash.

The hash-chain linkage is the integrity guarantee; accepting an entry whose prev_log_hash does not match the local tail would introduce a fork in the replica's chain.
SBT-02-008 MUST On hash-chain mismatch in the non-case-actor path, the participant MUST send Reject(CaseLedgerEntry) back to the case-actor with its last-accepted hash.

The Reject triggers the case-actor's replay path (SYNC-03-002), which resends all entries from the last accepted position forward so the participant can converge.
SBT-02-003 MUST The participant path MUST check for a duplicate entry before persisting (idempotency).

Retries and replay can deliver an announcement more than one time. Without a duplicate check, the replica stores the repeat twice. Or, the repeat fails the chain check and causes an unnecessary reject and replay.
Implements: SYNC-03-003 — Idempotent delivery
SBT-02-012 MUST When the participant path finds the entry already stored, the BT MUST return SUCCESS without persisting it again.

A repeat of a stored entry is a delivery already handled. A SUCCESS with no write keeps the replica unchanged and does not read the repeat as an error.
Extends: SBT-02-003
SBT-02-004 MUST The case-actor path MUST verify that the log entry's sender matches the case-actor's own identity (actor-ID comparison).

Only the CASE_MANAGER writes the canonical ledger. Thus an entry that claims to come from the CASE_MANAGER but has a different sender is not authentic. The identity check prevents other actors from writing into the canonical ledger.
SBT-02-009 MUST On sender-identity mismatch (potential injection attempt) in the case-actor path, the BT MUST log at WARNING level including the activity_id and the mismatched actor IDs.

A WARNING-level log with the mismatched IDs provides an auditable record of potential injection attempts without exposing internal state to the sender.
SBT-02-010 MUST On sender-identity mismatch in the case-actor path, the BT MUST return FAILURE without persisting.

Persisting a log entry whose sender does not match the case-actor's own identity would allow injection of forged entries into the canonical ledger.
SBT-02-005 SHOULD The case-actor path's sender verification SHOULD be designed as a replaceable condition node so that cryptographic signature verification can replace actor-ID comparison in a future phase without restructuring the tree.

Actor-ID comparison trusts the sender identity that the message claims. A single replaceable condition node lets a stronger check, such as a signature, replace the comparison later. The tree around the node does not change.
SBT-02-006 MUST When the case-actor receives a valid round-trip of its own log entry, the BT MUST log at DEBUG level (delivery round-trip confirmation) and return SUCCESS. No state update or re-persistence is performed.

The CASE_MANAGER already holds the entry that it announced, so its own echo carries no new data. When the echo is a success with no write, the round trip does not change the canonical ledger and does not show as an error.

RejectLogEntryReceivedBT

ID Priority Requirement Related
SBT-03-001 MUST RejectLogEntryReceivedBT MUST update the VultronReplicationState for the rejecting peer with the last-accepted hash reported in the rejection.

Replay starts from the entry that the peer accepted last. When the CASE_MANAGER records that position for each peer, it sends again only the entries that the peer does not have. The position also stays available for later replays.
Implements: SYNC-04-001 — Per-peer replication state tracking
SBT-03-002 MUST After updating replication state, RejectLogEntryReceivedBT MUST replay all missing entries from the peer's last-accepted hash forward by queuing Add(CaseLedgerEntry) activities via SyncActivityPort, unless the replay rate bound suppresses the replay (SYNC-15-009) or the Reject is declined as already answered (SYNC-15-024).

A peer that rejected an entry stays behind until it gets all entries after its last accepted entry. When the CASE_MANAGER replays that full range through the port, the replica gets the entries in order and becomes equal to the canonical ledger.
Implements: SYNC-03-002 — Retry from last-accepted hash
Uses definition from: SYNC-15-009
Uses definition from: SYNC-15-024
SBT-03-003 MUST RejectLogEntryReceivedBT MUST resolve the case-actor for the referenced case and use the case-actor's identity as the sender for replayed Add(CaseLedgerEntry) activities.

Ledger entries replicate in one direction, from the CASE_MANAGER to each participant (SYNC-00-002). A participant replica accepts case-state updates only from the CASE_MANAGER for that case (PCR-03-001). Thus a replay sent under another identity does not bring the replica up to date.

CommitLogEntryBT

ID Priority Requirement Related
SBT-04-001 MUST CommitLogEntryBT MUST compose as a Sequence of discrete BT nodes: (1) reconstruct chain tail hash, (2) create CaseLedgerEntry with computed entry_hash, (3) persist entry to DataLayer, (4) fan out Add(CaseLedgerEntry) to case participants via SyncActivityPort.

Each step of a commit can fail independently. The chain tail can fail to rebuild, the write can fail, or the port can be missing. When each step is a discrete node in a Sequence, the commit stops at the failed step, and the trace names that step. Each step can also be tested and reused alone.
SBT-04-002 MUST Fan-out MUST be a separate BT action node (not inlined into the persist step) so that the commit and replication concerns are independently testable and composable.

Persistence and announcement fail for different reasons, and have different tests. A separate fan-out node can be reused and tested with a fake port. It also goes after the persist step, so a failed write never announces an entry that does not exist.
SBT-04-003 MUST CommitCaseLedgerEntryNode in vultron/core/behaviors/case/nodes/lifecycle.py MUST commit each ledger entry by running CommitLogEntryBT (create_commit_log_entry_tree), the one commit path.

One commit path makes sure that each ledger entry is built, chained and announced in the same way. If the case node kept its own procedural commit, the two paths could create entries with different hashes or skip the fan-out. Ledger commits go only through CommitCaseLedgerEntryNode (BT-06-006).
SBT-04-004 MUST CommitLogEntryBT MUST fan out a log entry only after it has durably persisted (committed) the entry.

The fan-out is the record's delivery, so it follows the record. A failed write then never announces an entry that does not exist.
SBT-04-005 MUST An emit node MUST append its activity to the outbox before it runs the commit tree that records the activity, never running that commit first. This applies to every emit node whose activity the ledger records.

The activity the record describes is the act, so it precedes the record (ADR-0119).
Refines: SYNC-09-002 — Send-then-commit order (ADR-0119)

Port Injection via Blackboard

ID Priority Requirement Related
SBT-05-001 MUST BTBridge MUST inject every driven port that BT nodes use through its blackboard context, in one consistent pattern. The ports include DataLayer, SyncActivityPort and any future port.

With one injection pattern, all nodes find their ports in the same way. Then a test or a new deployment can supply all ports in one location.
SBT-05-003 MUST A BT node MUST read its ports from the blackboard at update() time, never at construction time.

When a node reads its ports at update() time, each run uses the ports set up for that run, not ports captured at tree build time.
Extends: SBT-05-001
SBT-05-002 MUST The blackboard key for an injected port MUST be one fixed {noun} name per port, with no id suffix and no slash. The established keys include datalayer, sync_port, wire_render_port, inbox_queue, inbox_dereference and inbox_replay.

py_trees reads a slash in a key as a namespace separator. Thus a key built from a full URL id splits into nested namespaces, and the lookup fails. Fixed, shared key names let all nodes read an injected port, and no node must know which code set the port. A port is one per run, not one per correlated object, so there is no id to scope its key by. This is the port exception to the {noun}_{id_segment} rule of BTND-03-008.
Supersedes: BTND-03-008 — Exempts injected-port keys from the {noun}_{id_segment} rule; every other blackboard key still follows it.

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

Replication Transport

ID Priority Requirement Related
SYNC-02-005 MUST This codebase MUST embed the full inline CaseLedgerEntry in the object of each Add(CaseLedgerEntry), never a URI-only reference.

An inline entry lets the recipient check the hash chain without a request back to the sender. This codebase never fetches a ledger entry that a message names by reference, so without the inline entry a recipient in this codebase could not apply the Add at all. An entry fetched by reference passes the same checks, so another implementation may send a reference (SYNC-02-004).
Refines: SYNC-02-004

Conflict Handling

ID Priority Requirement Related
SYNC-03-010 MUST When this codebase's CASE_MANAGER receives the SYNC-03-007 fault from an active participant of the case (CM-10-004), it MUST log the fault at ERROR.

The fault's purpose is to make the problem visible where the ledger is kept.
Uses definition from: CM-10-004
Uses definition from: SYNC-03-007
SYNC-03-015 MUST When this codebase's CASE_MANAGER logs the fault under SYNC-03-010, it MUST recompute the hash of its own stored copy of the named entry. It recomputes it as SYNC-03-006 does.

The self-check says which side is broken (SYNC-03-008): the CASE_MANAGER's stored entry, or the wire form between the two actors.
Extends: SYNC-03-010
Uses definition from: SYNC-03-006
SYNC-03-016 MUST When this codebase's CASE_MANAGER logs the fault under SYNC-03-010, it MUST log the result of the SYNC-03-015 self-check. The result says whether its copy is intact, or that it holds no copy of the named entry.

An operator reads the log to decide what to repair. The self-check result in the log says whether the stored entry or the wire form is at fault.
Extends: SYNC-03-010
Depends on: SYNC-03-015

Per-Peer Replication State

ID Priority Requirement Related
SYNC-04-002 MUST Per-peer replication state MUST be persisted via the DataLayer so that it survives a leader restart

If a restart loses the per-peer state, the leader forgets which peers are behind and how recently it replayed to them. The replay cooldown then starts again from zero, and a stuck peer can again cause replays without limit (SYNC-15-003).

Retry and Backoff

ID Priority Requirement Related
SYNC-05-002 SHOULD Retry and backoff parameters SHOULD be configurable

Network latency and peer load differ between deployments, tests and production. One fixed set of values is too slow for some deployments and too aggressive for others.
SYNC-05-003 MUST Default values for retry and backoff parameters MUST be documented

An operator must know the default values to decide whether to change them. A test author also needs them to know how long a recovery can take.
SYNC-05-004 MUST The delivery adapter MUST expose the per-recipient HTTP POST timeout as a configurable parameter with a documented default value.

A configurable timeout lets each deployment fit its load (SYNC-05-002). Other implementations can set this adapter limit differently, so it is project (ADR-0134).
SYNC-05-005 MUST The default per-recipient HTTP POST timeout MUST tolerate a recipient that is briefly busy under normal protocol load, such as one draining its own outbox. A value of 5 seconds or less is too short under CI-representative multi-actor load.

A busy recipient, for example one that sends its own outbox, can take several seconds to answer. A short timeout marks a working delivery as a failure, and the retries add more load to that recipient. A value of 5 seconds or less fails this way under multi-actor load such as CI.
Extends: SYNC-05-004

Leadership and Ownership

ID Priority Requirement Related
SYNC-06-004 SHOULD A future multi-node CASE_MANAGER cluster (Phase 3) SHOULD provide high-availability write authority through Raft consensus, which elects a single write authority among the CASE_MANAGER nodes.

A CASE_MANAGER that runs on one node stops the case when that node fails. A Raft cluster keeps one node able to commit while the others stand by, so the single-writer rule (SYNC-01-004) still holds.
SYNC-06-005 SHOULD NOT An implementation SHOULD NOT conflate the CASE_MANAGER cluster of SYNC-06-004 with participant replication (LedgerFanout). In LedgerFanout the CASE_MANAGER pushes committed entries to participants in Add(CaseLedgerEntry). The two tiers operate independently.

Participant replication and a highly available CASE_MANAGER solve different problems. Participant replication sends committed entries to other actors. A Raft cluster decides which CASE_MANAGER node may commit. If the two tiers are mixed, a participant could seem to take part in the choice of the case's writer, which the single-writer rule forbids (SYNC-01-004).
Uses definition from: SYNC-06-004

Commit Discipline

ID Priority Requirement Related
SYNC-09-003 MUST The CASE_MANAGER's behavior tree execution MUST be gated on holding the replication leadership role.

In single-node deployments this gate is trivially satisfied. In multi-node deployments it prevents a deposed leader from continuing to write to the ledger after a new leader is elected.
SYNC-09-004 MUST In a multi-node deployment, the CASE_MANAGER's replication leadership gate MUST be checked against the Raft leader state.

Raft leader state is the authoritative source of leadership in a multi-node cluster; checking any other mechanism risks split-brain writes.

Testing

ID Priority Requirement Related
SYNC-07-001 MUST Unit tests MUST cover append-only semantics: entries are immutable, hashes are unique, and predecessor hash references are set correctly

Immutable entries, unique hashes and correct predecessor links are what every other replication rule depends on. A fault in them breaks every replica, so unit tests must find it before integration tests do.
SYNC-07-002 MUST Integration tests MUST cover the full single-peer replication cycle: leader appends an entry, sends an Add activity, and the receiver validates the predecessor hash and appends the entry

Each step can pass its own unit test while the steps fail together, for example when the sender and the receiver disagree on the wire form. Only a test of the full cycle shows that an entry gets from the leader into a replica.
SYNC-07-003 MUST Tests MUST cover conflict and idempotency scenarios: mismatched predecessor hash, duplicate delivery, and leader retry after rejection

A mismatched hash, a duplicate delivery and a retry after a rejection are the normal results of an unordered transport that can lose messages. These paths run less often than the normal path, so a fault in them can stay hidden without a test.
SYNC-07-004 MUST Unit tests MUST cover pending-assertion suppression semantics: add, is_suppressed, clear, timeout expiry, zero-timeout disable, and the expire_timed_out sweep helper.

The pending-assertion store decides whether a participant sends an assertion again. A fault in it either sends duplicates to the CASE_MANAGER or stops a resend that the case needs. Each operation has its own edge case, such as a zero timeout that turns suppression off, so each needs its own test.
SYNC-07-005 MUST Unit tests MUST cover per-actor pending-assertion store isolation via the module-level registry: distinct store instances per actor, configurable timeout applied on first creation, and the reset_pending_assertion_stores cleanup.

Several actors can run in one process, for example in tests and in the demo. If two actors share one store, a pending assertion of one actor suppresses a send of the other. A store that a test leaves behind can also change the result of a later test.

Participant-Local Pending Assertion Suppression

ID Priority Requirement Related
SYNC-11-001 SHOULD A participant actor SHOULD maintain an actor-local, in-memory pending-assertion store that records outbound assertion activities (e.g., Add(Note)) emitted toward the CASE_MANAGER but not yet confirmed by a canonical Add(CaseLedgerEntry) round-trip; the suppression window is configurable and zero disables suppression

An assertion takes time to come back as a committed entry, and meanwhile the participant's logic can decide to send it again. Without a record of what is pending, the CASE_MANAGER receives duplicates. The window matches the round-trip time; zero turns it off. The store only saves traffic: each repeat kind it suppresses needs its own no-op rule at the CASE_MANAGER (ID-04-004, CM-13-005, EP-09-032), as a replica cannot see a repeat's effect before the round trip returns (CLP-07-013).
SYNC-11-002 SHOULD After a participant successfully enqueues an assertion activity toward the CASE_MANAGER, the participant SHOULD record the (case_id, semantic_type, activity_id) triple in its pending-assertion store so that duplicate near-term re-emits of the same assertion are suppressed while the round-trip is pending

The triple identifies the pending assertion exactly enough to match a later send of the same assertion. Recording it only after the enqueue succeeds means that a failed send is never suppressed.
SYNC-11-003 SHOULD When a participant receives a matching Add(CaseLedgerEntry) whose log_object_id equals a pending assertion's object_id, the participant's pending-assertion store SHOULD clear the matching entry so that future re-emits of the same triple are no longer suppressed

The matching entry proves that the CASE_MANAGER committed the assertion. After that, a later send of the same triple is a new decision, not a duplicate, so the store must not suppress it.
SYNC-11-004 MUST NOT The CASE_MANAGER MUST NOT use the pending-assertion store for its own ledger commits; the CASE_MANAGER's DataLayer idempotency check already guards against duplicate commits by the single authoritative writer

The CASE_MANAGER commits its own entries, so it has no round trip to wait for. Its DataLayer idempotency check already stops duplicate commits. A second mechanism on that path could suppress a commit that the case needs.
SYNC-11-005 SHOULD This codebase SHOULD mark a pending assertion timed-out when it exceeds its configured timeout window.

An assertion can be lost in transit or refused, and then no matching entry comes back. A timeout marks the point after which the participant stops waiting for it.
SYNC-11-006 SHOULD NOT A timed-out pending assertion (SYNC-11-005) SHOULD NOT suppress later re-emits, so an operator retry or the catch-up gate can submit the assertion again.

Without this, the store would suppress every later send of a lost assertion, and the participant could never make the assertion again. The timeout does for this store what an ask's expiry does for the outstanding-ask register (ASK-04-007), and it is not a second duplicate check, so a repeat it lets through is safe at the CASE_MANAGER.
Extends: SYNC-11-005

Ledger Write Ownership and Layer Boundary

SYNC-12's already-stored gate (SYNC-12-003) uses the presence of a CaseLedgerEntry in an actor's DataLayer as the sole evidence that the entry's effects were already applied. That inference is only sound if the ONLY thing that ever writes a CaseLedgerEntry to the DataLayer is the core write path that also applies the effects. If any other layer (e.g. a wire/adapter parse or rehydration helper) creates a CaseLedgerEntry record, the gate fires SUCCESS on first delivery and the effects are silently skipped. These requirements make the write-ownership boundary that SYNC-12 depends on explicit.

ID Priority Requirement Related
SYNC-13-001 MUST A CaseLedgerEntry record is written to an actor's DataLayer ONLY by that actor's core ledger write path — the CASE_MANAGER's authoritative append (SYNC-01-004) for its own case, or a participant's PersistReceivedLogEntry step (SYNC-12-001) for a replica. Presence of a CaseLedgerEntry in the DataLayer is defined to mean "this actor's core has committed the entry and applied its effects."

The already-stored check (SYNC-12-003) reads a stored entry as proof that its effects were applied. That proof holds only when the code that stores the entry is the code that applies its effects. If another path stores an entry, the check succeeds on first delivery and the effects never run.
Uses definition from: SYNC-01-004
Uses definition from: SYNC-12-001
SYNC-13-002 MUST NOT Adapter, wire, transport, and message-parsing code MUST NOT create, save, or otherwise persist a CaseLedgerEntry to the DataLayer.

Ingress code delivers the message; it does not write the ledger. Any ingress write would bypass the write-ownership guarantee that SYNC-12 depends on and silently skip effects on first delivery.
SYNC-13-003 MUST NOT Message ingress MUST NOT use the canonical ledger/DataLayer store as a scratch or lookup cache for routing, semantic classification, or rehydration of an inbound Add(CaseLedgerEntry).

If ingress stores an inbound entry to classify or rehydrate it, the entry is in the DataLayer before its effects run. The already-stored check (SYNC-12-003) then skips the effects on first delivery (SYNC-13-001).
SYNC-13-008 MUST Message ingress MUST carry the inline CaseLedgerEntry parsed from the wire envelope forward in memory, or in a dedicated non-ledger holding area. Semantic routing and effect application then do not depend on pre-storing the entry.

Routing still needs the entry. An in-memory entry lets routing work without the ledger write that SYNC-13-003 forbids.
Implements: SYNC-13-003
SYNC-13-007 MUST This codebase MUST resolve an inbound Add(CaseLedgerEntry) to the log-entry semantic (ADD_CASE_LEDGER_ENTRY_TO_LEDGER) on first delivery using the typed inline object obtained during parsing, without a DataLayer round-trip.

This codebase never fetches a ledger entry that a message names by reference, so the inline object is the only input the classifier has. Classification from it works because this codebase sends the entry inline (SYNC-02-005). A classifier that needed a stored entry would fail on the first delivery of each entry, which the receiver has not stored yet.
Implements: SYNC-13-004

Out-of-Order Entry Buffering and Drain

Add(CaseLedgerEntry) is delivered over a transport with no ordering guarantee, and Vultron may not be the only implementation on the wire, so a replica can receive an entry before its hash-chain predecessor. Dropping such an entry and relying on a reject/replay round-trip does not converge under adversarial reordering, because replay re-announces entries individually over the same unordered transport (they can reorder and be dropped again). These requirements make replica convergence independent of delivery order by holding the received Add of a forward-gap entry in a non-ledger holding area and replaying it, in hash-chain order, once the entry that closes the gap is committed. What is held and replayed is the Add that was received, never one the replica builds. Rationale: ADR-0037 (docs/adr/0037-buffer-out-of-order-ledger-entries.md), ADR-0214.

ID Priority Requirement Related
SYNC-14-009 MUST When a held Add(CaseLedgerEntry) becomes appliable (SYNC-14-003, SYNC-15-005), the drain MUST replay it as a delivery of its own. The replay runs through the inbox's sole entry point (IO-02-003), under the receiving actor, never inside the delivery that made it appliable. The replayed Add's own tree replays the next one, so the cascade needs no loop in the use case.

One delivery runs one tree (CLP-10-005), so a drain that ran its successor inline would run several trees in one delivery. A drain inside the tree would run one tree inside another, and an internal error in the inner tree would then not be reported. A delivery of its own goes through the same path as in-order delivery (SYNC-14-008, ADR-0214).
Implements: SYNC-14-008
Derives from: CLP-10-005
Implements: SYNC-14-003
Uses definition from: IO-02-003
SYNC-14-015 MUST The drain MUST replay the Add(CaseLedgerEntry) that was received, parsed again from the body held for it (VM-08-008). The replay then carries the first delivery's received evidence.

Intake archives what it receives as received evidence. A replay parsed from that body is the Add that arrived, with its own id and sender.
Extends: SYNC-14-009
Refines: VM-08-008
SYNC-14-016 MUST NOT A participant MUST NOT replay an Add(CaseLedgerEntry) it built itself, or one it attributes to a sender that did not send it.

A receiver that did not receive an Add cannot make one up. A made-up Add would name a sender that never sent it, and its received evidence would be false.
Extends: SYNC-14-009
SYNC-14-005 MUST NOT The out-of-order holding area MUST NOT be the canonical ledger.

A stored CaseLedgerEntry means that the entry is committed and its effects are applied (SYNC-13-001). A held entry has neither, so the place that holds it must be apart from the ledger.
SYNC-14-011 MAY The holding area MAY keep a held Add in the receiver's DataLayer, but only as records of its own kind, never as a CaseLedgerEntry.

A held Add has to survive a restart, so the DataLayer is a fit place for it. A record of its own kind keeps it apart from the ledger entries that SYNC-13-001 reads.
Extends: SYNC-14-005
SYNC-14-012 MUST NOT A participant MUST NOT persist a held entry as a CaseLedgerEntry until it is drained, that is, until its predecessor is present. A stored CaseLedgerEntry then still means "committed and effects applied" (SYNC-13-001).

If the holding area stored a held entry as a ledger entry, the already-stored check would skip its effects when it drains.
Extends: SYNC-14-005
Uses definition from: SYNC-13-001 — Holding an entry as a CaseLedgerEntry would break the presence-means-committed invariant
SYNC-14-006 SHOULD This codebase SHOULD bound the holding area in size per case.

A peer that sends many entries, or a long gap, could fill the receiver's store without limit.
SYNC-14-013 SHOULD When the holding area is full, it SHOULD drop the Add whose entry is farthest ahead of the current gap (highest log_index). When a held one is farthest ahead, it evicts that one, body and all, and logs a warning. When the new entry is itself the farthest ahead, it declines to hold the new one.

The entry farthest ahead is the last one the drain needs, so dropping it loses the least. Eviction is safe because the Reject (SYNC-14-002) already asked for a replay, and the replay sends the entry again.
Extends: SYNC-14-006
SYNC-14-014 MUST NOT This codebase MUST NOT rely on an eviction under SYNC-14-013 to trigger recovery by itself.

Eviction is recoverable only because SYNC-14-002 already sent a Reject. An eviction that was expected to start recovery would strand the evicted entry when no Reject went out.
Extends: SYNC-14-013

Genesis-Unavailable Buffer-and-Reject

A participant replica receives Add(CaseLedgerEntry) activities from the CASE_MANAGER over an unordered transport. If the CASE_MANAGER delivers a ledger entry before the Create/Announce(VulnerabilityCase) activity has been processed by the participant (a delivery race under HTTP BackgroundTasks), the replica cannot reconstruct the per-case genesis hash (CLP-08-005) and must not silently drop the entry. Silently dropping causes the entry to be permanently lost because the CASE_MANAGER never learns that delivery failed and never replays. A pre-genesis entry is therefore held in the same non-ledger holding area used for forward gaps (SYNC-14) and drained once the case seed anchors the genesis hash, making convergence independent of whether the case or its ledger entries arrive first (issue #2186, #2180). A Reject is still sent as the loss backstop, triggering the same replay path as the hash-mismatch case (SYNC-08-005, SYNC-14-002) for an entry that is genuinely lost rather than merely early. The backstop is asked once per wait, not once per held entry, and the CASE_MANAGER answers once per need; both limits are rate limits, never stops (SYNC-15-016 to SYNC-15-025, ADR-0168). The forward-gap hold of SYNC-14 alone does not cover this window: it only holds entries for a case whose genesis anchor is already known, so a distinct pre-genesis hold and a drain triggered by the case seed are required. Rationale for the buffer-and-drain path (SYNC-15-004, SYNC-15-005): ADR-0059 (docs/adr/0059-buffer-pre-genesis-ledger-entries.md).

ID Priority Requirement Related
SYNC-15-008 MUST The CASE_MANAGER MUST record, per peer, the position (the entry_hash a replay resumed from, or "" for genesis) of the last replay in which at least one entry was actually sent, together with the time it was sent.

Recording the position and timestamp of the last non-empty replay is the data the cooldown check needs to determine whether a subsequent Reject at the same position falls within the cooldown window.
SYNC-15-009 MUST NOT A Reject reporting an unchanged replication position within the cooldown MUST NOT trigger another replay.

A peer that cannot anchor its hash chain rejects every entry replayed to it, which makes a loop that sustains itself. A Reject at the same position inside the cooldown carries no new information, so suppressing its replay breaks the loop. A Reject after the cooldown still gets a replay, so a lost replay is repaired.
SYNC-15-010 MUST A Reject reporting an advanced replication position MUST always trigger a replay.

An advanced position means the peer successfully committed at least one entry since the last replay; withholding replay at that point would stall convergence.
SYNC-15-011 MUST NOT A replay in which zero entries were sent MUST NOT update the recorded position, because no delivery was attempted at that position.

A replay that sent nothing gave the peer nothing to act on. Recording its position would start a cooldown, and that cooldown would suppress the first replay the peer actually needs when the ledger grows.
SYNC-15-012 MUST NOT The CASE_MANAGER MUST NOT enqueue a replay Add(CaseLedgerEntry) for an (entry, peer) pair while an earlier Add of that same entry to that same peer is still pending in its outbox.

A Reject that arrives after the peer's gap has drained still reports an advanced position, so SYNC-15-010 replays. The replayed entries are often still in the outbox from the last replay. Queuing them again puts duplicate Adds in front of the next entry's fan-out to every other peer. This rule stops only a second copy of the same row, and the replay itself still occurs (ADR-0112).
Extends: SYNC-15-003
SYNC-15-013 MUST The CASE_MANAGER MUST lengthen the cooldown after each consecutive non-empty replay it sends a peer from an unchanged replication position. It doubles the cooldown each time, up to a fixed ceiling.

A fixed cooldown ends the Reject and replay loop only when one round trip completes inside it. On a loaded host, or with a peer that can never anchor its chain, the loop runs for as long as the peer rejects. A cooldown that doubles soon makes replays to a stuck peer rare, whatever the round-trip time. The ceiling makes sure that a stuck peer still gets a replay at a fixed interval, so the cooldown is a rate limit and not a stop (SYNC-15-003 note).
Implements: SYNC-15-003
Depends on: SYNC-15-008 — The per-peer record carries the count of replays at its position
SYNC-15-026 MUST A replay the CASE_MANAGER sends to a peer from a different replication position MUST reset the cooldown to its base value.

A changed position means the peer made progress, so it is not stuck. Starting again from the base cooldown keeps a peer that is catching up from waiting out a backoff it earned while stuck.
Extends: SYNC-15-013
SYNC-15-014 MUST NOT The CASE_MANAGER MUST NOT send the genesis Announce(VulnerabilityCase) pre-seed (SYNC-15-015) in answer to a genesis Reject whose replay the cooldown suppresses.

The pre-seed exists to anchor the replay that follows it. While the cooldown suppresses that replay, the peer already holds the case sent with the last one. A pre-seed for each Reject would keep one message moving for each Reject in the loop that SYNC-15-003 limits.
Extends: SYNC-15-003
Uses definition from: SYNC-15-015
SYNC-15-020 MUST The interval of SYNC-15-016 MUST be the replay cooldown's ceiling of SYNC-15-013, 600 seconds, read from the one constant that sets that ceiling.

The participant's interval sets how long a participant waits before it asks again after a lost replay, once a further entry for the missing case arrives. Using the ceiling the CASE_MANAGER already applies to a stuck peer keeps one number for "how long a stuck replica may wait", and a shared constant keeps the two from drifting apart.
Refines: SYNC-15-016
Uses definition from: SYNC-15-013
SYNC-15-021 MUST A participant MUST record, per case it does not hold, the time it last sent a genesis Reject for that case, in its own store as a record of its own kind.

The participant decides SYNC-15-016 when an early entry arrives, so it needs the time of its last request then; no existing record carries it, since a held Add has no timestamp. Keeping it in the store survives a restart.
Implements: SYNC-15-016
SYNC-15-022 MUST The CASE_MANAGER MUST record, per peer, the highest log_index its last non-empty replay from genesis sent.

The CASE_MANAGER decides SYNC-15-019 when a genesis Reject arrives, so it needs to know which entries its last replay from genesis already resent. The position record of SYNC-15-008 names only where a replay started, not how far it reached.
Implements: SYNC-15-019
Extends: SYNC-15-008
SYNC-15-023 MUST A participant MUST delete its record of SYNC-15-021 for a case when it seeds that case.

A record left behind after the seed would make a later genesis wait for the same case inherit an old time, so the participant could withhold that wait's first request.
Extends: SYNC-15-021
SYNC-15-024 MUST While the peer's recorded replay position (SYNC-15-008) is genesis and less than the replay cooldown's ceiling of SYNC-15-013 has passed since that replay, the CASE_MANAGER MUST decline under SYNC-15-019 a genesis Reject whose rejected entry is at or below the index of SYNC-15-022.

The genesis cooldown starts at 2 seconds, so on a loaded host every queued genesis Reject passed it and drew a full replay (#5552). A Reject of an entry the last replay resent is answered by that replay. A later entry still replays under the cooldown, and after the ceiling any Reject does (SYNC-15-018). A peer whose position moved past genesis and then reports genesis again has lost its copy, so the skip applies only while the recorded position is still genesis.
Refines: SYNC-15-019
Uses definition from: SYNC-15-022
Uses definition from: SYNC-15-008
Uses definition from: SYNC-15-013
SYNC-15-025 MUST NOT A genesis Reject the CASE_MANAGER declines under SYNC-15-024 MUST NOT update the peer's recorded replay position, its time or its replay count.

A declined Reject sent nothing, so recording it would start or lengthen a cooldown against a replay that never happened, as SYNC-15-011 rules out for an empty replay.
Extends: SYNC-15-024

Divergence Recovery

Under the copy model (ADR-0124) a replica applies each entry through one apply function that refuses an entry whose starting state does not match the replica's case file. When the refused entry already extends the replica's stored chain, no replay can fill the gap: the replica's case file has diverged from the CASE_MANAGER's, and the reject and replay path resends the same refused entry forever. A divergence is a defect, not a steady state, so the replica reports it and the CASE_MANAGER repairs it with a fresh case copy that names the ledger position it reflects. The fault is replication signalling, like the gap Reject, and is never ledgered. Rationale: ADR-0142.

ID Priority Requirement Related
SYNC-16-008 SHOULD The CASE_MANAGER SHOULD log at ERROR a SYNC-16-001 fault for an entry at or before the tail of the last re-seed it sent that peer only when the peer's acknowledged position is at or past that tail and the fault's claimed published time is after the time the peer claimed for that acknowledgement. Any other such fault is ordinary recovery, logged below ERROR and left to the rate-bounded re-seed (SYNC-16-004).

A peer that acknowledged the copy's position has applied a case that already reflects the entry, so a refusal it sends afterwards means the CASE_MANAGER's own case disagrees with its ledger: a defect, not recovery, and it must not read as routine. Without the acknowledgement the same fault is ordinary recovery: the copy may have been lost in transit, or the entry replayed before the copy arrived. A fault the peer sent before acknowledging is recovery too: a replay refused before the copy arrived, delivered late because arrival order is not guaranteed (SYNC-19). A tie counts as recovery: a Vultron peer writes microseconds (CS-13-007), so its refusal and the acknowledgement that follows it rarely tie, but a peer may claim whole seconds, and then the two can share a second; a defect fault sent in that same second reads as recovery once. The two times compared are both the peer's own claims, so they share its clock and no skew between machines enters the comparison. The acknowledgement's time is the peer's first statement of that position, so a later restatement cannot hide a fault sent after it; a peer that moves on to a later position takes that statement's time, so a defect fault sent in between reads as recovery once, and the defect shows at ERROR on the next repeat. A missing time on either side shows no order and keeps the ERROR. Logging recovery at ERROR would mark a self-healing path as a failure.
Uses definition from: SYNC-16-001
See also: SYNC-16-004 — a logging rule is not a case of the rate bound

Participant Position Statements

A participant's replica can fall behind with nothing to show it: when the last Add(CaseLedgerEntry) before a quiet period is lost, no later entry arrives with a gap, so no Reject(CaseLedgerEntry) is sent and the reject-and-replay loop never starts. The CASE_MANAGER cannot see the lag either, because nothing tells it how far a participant has got. The participant therefore states its position, when it chooses, in a Read(<case>/ledger), a Read of the case's ledger, and the CASE_MANAGER replays every entry after that position. A position behind its tail, or the empty ledger's at index -1, so asks for a replay. The position stated on every case activity (SYNC-18) composes the same answer. This is how the LedgerReconciliation phase detects a gap and retries until convergence (SYNC-00-003, SYNC-00-007, SYNC-00-008). Rationale: ADR-0155, ADR-0204.

ID Priority Requirement Related
SYNC-17-007 SHOULD The reference implementation's participant SHOULD send Read(<case>/ledger) for each case it holds after a restart.

When to check is the participant's own policy (ADR-0155). A restart is the moment it is most likely to have missed an entry.
SYNC-17-011 SHOULD The reference implementation's participant SHOULD support sending Read(<case>/ledger) on a configurable interval. The interval is off by default, and that default is documented beside the retry defaults (SYNC-05-003).

A periodic check costs traffic that a deployment should choose, so the default sends none.
Extends: SYNC-17-007
See also: SYNC-05-003 — context for the reader

Resending Unanswered Invites

An Invite can be lost before its addressee can answer it. A joiner's relayed Invite(EmbargoEvent) or full-case Invite that arrives before its case copy waits in the pre-bootstrap queue, and is dropped when the queue's window ends (CBT-03-003); any Invite can be lost in delivery. A participant that states its ledger position tells the CASE_MANAGER its replica holds the case, which is the moment a resent Invite can be answered. So the CASE_MANAGER resends each Invite the participant still owes an answer to, as first sent and rate-bounded per Invite and participant. Rationale: ADR-0163.

ID Priority Requirement Related
SYNC-20-006 MUST The resend cooldown's base and ceiling (SYNC-20-005) MUST be configurable, with their defaults documented beside the retry defaults (SYNC-05-003).

How often to ask again is a deployment trade-off between recovery time and traffic, and an operator must know the defaults to change them.
Uses definition from: SYNC-20-005
See also: SYNC-05-003 — says where defaults are documented; the resend cooldown is not a retry parameter

Sender Sequence on Participant Case Activities

Two activities one participant sends to the CASE_MANAGER can arrive in either order, and their ledgerPosition cannot tell them apart when the first is not yet committed. So each participant numbers its case activities per case, and the CASE_MANAGER judges each sender's activities in that order. An activity past a gap waits in a bounded hold; when the hold ends, the gap is skipped. A number that arrives after its gap was skipped is never applied, and it and a missing number are refused with a notice. This is how the CASE_MANAGER meets SYNC-19-001 for one sender's assertions. Rationale: ADR-0178.

ID Priority Requirement Related
SYNC-21-004 MUST This codebase MUST produce senderSequence only in vultron.wire.as2.factories.

One producer gives one place that decides which activities are numbered and what number they carry, as for ledgerPosition (SYNC-18-008).
Refines: SYNC-21-001
SYNC-21-020 MUST This codebase MUST keep sequence state in the DataLayer: each participant's last number per case, and the CASE_MANAGER's expected numbers and held activities.

State kept only in memory would be lost on a restart. A participant would then reuse numbers, and the CASE_MANAGER would lose held activities and judge a sender's next activity out of order.
Refines: SYNC-21-002
Refines: SYNC-21-010
SYNC-21-021 SHOULD This codebase SHOULD make the hold's wait and per-sender cap configurable, defaulting to 120 seconds and 16 activities, documented beside the retry defaults (SYNC-05-003).

The wait trades the delay a gap causes against the chance that a reordered activity arrives in time, which depends on the deployment. The default covers a delivery attempt that times out and its retries, and ends before the default pending-assertion timeout (SYNC-11-005).
Refines: SYNC-21-011
Refines: SYNC-21-012
See also: SYNC-05-003 — location only: the defaults are documented beside SYNC-05-003's, and neither requirement constrains the other
SYNC-21-022 SHOULD This codebase SHOULD log at WARNING each number the CASE_MANAGER skips, with the sender and the case.

A skipped number means an activity was lost or delayed past the wait. The CASE_MANAGER recovers by itself, so the event is a warning, not an error, and the log is how an operator finds a sender whose activities are being lost.
Refines: SYNC-21-013

Vultron Project Technology Stack

This specification defines the normative technology constraints and implementation requirements for the Vultron reference implementation.

File ID: IMPLTS

Runtime and Language

ID Priority Requirement Related
IMPLTS-01-001 MUST The implementation MUST use Python 3.14 or later.

A minimum Python version tells users and contributors which interpreters the code supports. CI and the container images run Python 3.14, so 3.14 is the oldest version the code is tested on. A lower floor would be a claim nothing tests.
IMPLTS-01-009 MUST Ruff's target-version, mypy's python_version, pyright's pythonVersion and the setup-python-uv CI action's default interpreter MUST name the requires-python floor.

The floor is the oldest version the project claims to support. The static checks judge the code against the version they name, so a newer one accepts syntax the floor rejects, and an older one rejects syntax the floor accepts. A check that names no version follows the interpreter that runs it, so it too must name the floor. CI runs its default interpreter, so a default above the floor leaves the floor untested.
Refines: IMPLTS-01-001
IMPLTS-01-010 MUST The Docker base image MUST run the requires-python floor or a later Python version.

A container may run ahead of the floor, but one below it runs an interpreter the project does not support, so the shipped runtime contradicts the declared one.
Refines: IMPLTS-01-001
IMPLTS-01-007 MUST Before a maintainer raises the requires-python floor in pyproject.toml, the full test suite MUST pass on the target Python version in CI.

A new requires-python floor drops every older Python version at once. If the tests have not run on the new version first, a release can claim a version that it does not work on. A user then finds the fault after the install, not CI before the merge.
IMPLTS-01-008 MUST Before a maintainer raises the requires-python floor in pyproject.toml, mypy, pyright and the linters MUST pass under the new runtime.

Type checkers and linters can report a different result on a new Python version. A floor raised before they pass can ship code that the checks would refuse on the version the project now claims.
Extends: IMPLTS-01-007
IMPLTS-01-002 MUST The backend API MUST be implemented using FastAPI.

One web framework gives every actor endpoint the same request handling, validation and dependency injection. FastAPI uses the Pydantic models the project already has for its data (IMPLTS-01-004), and its BackgroundTasks let a route return at once and do the long work after the response.
IMPLTS-01-003 MUST The backend API MUST expose an OpenAPI specification.

Other implementations and tools must know the shape of each endpoint to call it correctly. An OpenAPI document gives that description in a machine-readable form. FastAPI generates it from the route definitions, so the document changes when the routes change.
IMPLTS-01-004 MUST The system MUST use Pydantic for data validation and data modeling.

One validation library gives every model the same rules for parsing, defaults and errors. Pydantic checks an object when it is constructed, so a bad value fails at once with a clear error and the core receives only valid objects (ARCH-10-001).
IMPLTS-01-005 MUST The application MUST use Python’s standard logging framework for structured logging.

FastAPI, uvicorn and httpx2 write their log output through the standard logging module. When Vultron uses the same module, one handler configuration controls all output in the process. The structured-logging rules (SL-01, SL-02) also rely on its record, filter and formatter types.
IMPLTS-01-006 MUST Behavior trees that run protocol behavior (vultron/core/behaviors/) MUST be implemented using py_trees.

py_trees gives the protocol behavior trees standard Sequence, Selector and condition semantics, a blackboard to pass data between nodes, and tree display for debugging (ADR-0008). The custom engine in vultron/bt/ serves the simulator. Keeping the two engines apart means that a change to the simulator cannot break protocol handling.

Persistence and Data

ID Priority Requirement Related
IMPLTS-02-001 MUST The prototype MUST use SQLModel/SQLite for lightweight local persistence.

The prototype needs persistence that runs with no database server. SQLite keeps the data in a local file, or in memory for tests. SQLModel stores each object as a typed row that holds its JSON body (ADR-0016).
IMPLTS-02-002 MUST The system MUST support SQLite-based storage for demo and local development use.

A demo or a local run must start with no extra service to install or run. SQLite is part of the Python standard library, so a contributor needs nothing beyond the project's own dependencies.
IMPLTS-02-003 MUST The system MUST support ISO 8601 date/time parsing and formatting using isodate.

Embargo policies give durations in ISO 8601 form, such as P90D. The Python standard library parses ISO 8601 dates and times but not durations, so the project uses isodate to parse and write them.
IMPLTS-02-004 MUST The system MUST support graph construction and analysis using networkx.

The case state model is a graph of CS states, and the spec tools build a graph of requirement relationships. networkx builds these graphs and finds paths through them. One graph library means that no code has its own graph algorithms to maintain.

Interfaces and Tooling

ID Priority Requirement Related
IMPLTS-03-001 MUST The product CLI (vultron/adapters/driving/cli.py) and the demo CLI (vultron/demo/cli/) MUST be implemented with click.

One CLI library gives each user-facing command the same option parsing, help text and environment-variable options. A user who knows one of the two CLIs knows how the other reads its options. The vultron/metadata tools and vultron/demo/report/ are project tooling, not user-facing CLIs, and keep the standard library's argparse.
IMPLTS-03-002 MUST The system MUST use httpx2, imported as httpx, for all HTTP client interactions, including outbound inbox delivery and demo HTTP calls.

One HTTP client gives one place to set timeouts and retries and one library to mock in tests. Outbound delivery, demo calls and the FastAPI test client then share one transport. pyproject.toml declares httpx2, and the code imports it under the name httpx.
IMPLTS-03-005 MUST NOT Code in this project MUST NOT use the requests library.

A second HTTP client library would need its own timeout, retry and mock code, and the two clients could then act differently on the same request.
Derives from: IMPLTS-03-002
IMPLTS-03-003 MUST The project MUST include automated tests implemented using pytest.

One test framework lets CI, the Makefile and each contributor run the whole suite with one command. The spec coverage report reads @pytest.mark.spec markers, and the suite runs in parallel with pytest-xdist, so both depend on pytest.
IMPLTS-03-004 MUST The project MUST support task automation using make.

The Makefile gives contributors short, named commands for setup, tests, formatting and linting. A contributor does not need to remember the full uv command for each task.

Documentation and Visualization

ID Priority Requirement Related
IMPLTS-04-001 SHOULD The project SHOULD generate static documentation using MkDocs.

The project publishes its protocol documentation as a static site. MkDocs builds that site from the Markdown files under docs/, which contributors edit in the same repository and pull requests as the code.
IMPLTS-04-002 SHOULD The documentation SHOULD use mkdocstrings for API reference generation.

An API reference generated from docstrings changes when the code changes. A reference written by hand goes out of date each time a signature changes and nobody edits the page.
IMPLTS-04-003 SHOULD The documentation theme SHOULD use Material for MkDocs.

Material for MkDocs gives the site its navigation, search and page layout. One theme gives every page the same structure, and the emoji extension uses the theme's icon set.
IMPLTS-04-004 SHOULD The documentation SHOULD support Mermaid diagrams for behavior trees, state machines, and process diagrams.

Behavior trees, state machines and message flows are easier to follow as diagrams. A Mermaid diagram is text in the Markdown page, so a reviewer sees each change to it in the diff, and no separate image file must be kept up to date.

Containerization and Deployment

ID Priority Requirement Related
IMPLTS-05-001 SHOULD The system SHOULD support containerization using Docker.

The multi-actor demo runs several actors at the same time. A container gives each actor its own process, data store and network address, as a separate organization would have. A contributor can start the whole set with one command.
IMPLTS-05-002 SHOULD Multi-container demo environments SHOULD be orchestrated using docker-compose.

One compose file declares all demo containers, their network names and their start order. The demo uses those names, such as case-actor, in actor addresses, so the file is also the record of who is in the demo.
IMPLTS-05-003 MUST The project MUST use GitHub Actions for CI/CD.

The source is on GitHub (IMPLTS-05-007). GitHub Actions runs CI next to the pull requests it checks, and other project automation, such as size labels and issue types, runs there too. One platform keeps all checks and their results on the pull request.
IMPLTS-05-004 MUST CI workflows MUST include automated testing.

A change that breaks a test must not reach main. CI runs the tests in a clean environment, so the result does not depend on what each contributor ran on their own machine.
IMPLTS-05-005 SHOULD CI workflows SHOULD support static site generation and deployment to GitHub Pages.

A docs build in CI finds a broken page or link before the change merges. A deploy from CI publishes the site from main, so the published docs match the merged code and nobody publishes by hand.
IMPLTS-05-006 SHOULD Static documentation SHOULD be hosted via GitHub Pages.

GitHub Pages serves the static site from the same repository, so the project has no separate web server to run. The homepage URL in pyproject.toml points to that site.

Code Quality Tooling

ID Priority Requirement Related
IMPLTS-07-002 MUST The project MUST use pyright for static type checking.

pyright is the type checker in common editors, such as VS Code through Pylance. When CI uses it too, a contributor sees the same type errors in the editor as in CI. mypy (IMPLTS-07-003) reads some typing rules differently, so the project runs both.
IMPLTS-07-003 MUST The project MUST use mypy for static type checking.

mypy is the reference type checker for the Python typing rules. It reports some errors that pyright does not, and pyright reports some that mypy does not, so the project runs both (IMPLTS-07-002).
IMPLTS-07-008 MUST All functions and methods MUST have cyclomatic complexity ≤ 10, the generally accepted upper bound for maintainable code. Enforced via max-complexity = 10 under [tool.ruff.lint.mccabe] in pyproject.toml, as part of the ruff CI gate and pre-commit hook.

A function with many branches is hard to read and hard to test on every path. A cyclomatic complexity limit of 10 keeps each function small enough to test fully. ruff rule C901 checks the limit. The pylint size rules (PLR09xx) stay off, so only one complexity check, with one limit, can fail a change.
IMPLTS-07-005 MUST The CI pipeline MUST run pytest, ruff (ruff check and ruff format --check), mypy and pyright as separate parallel jobs.

Parallel jobs report all failures in one CI run, so a contributor can fix them together and not one per run. ruff lint and format share one job: ruff does both in about a second, and a second job would take longer to start than it saves.
IMPLTS-07-022 MUST The CI build job MUST run only when every parallel check job passes.

When the build job waits for every check, the package is built only from code that passes every check.
Extends: IMPLTS-07-005
IMPLTS-07-006 MUST The pytest configuration in [tool.pytest.ini_options] MUST include filterwarnings = ["error"] so that test-suite warnings are treated as errors.

A warning in the test output is easy to miss, and a deprecation warning now is often a failure after the next dependency upgrade. When pytest treats each warning as an error, the run fails as soon as the warning appears, while the change that caused it is still known.
IMPLTS-07-009 MUST pyright MUST run in CI on every commit to main and on every pull request targeting main.

A type check that runs only on a contributor's machine can be skipped or run on a different scope. When CI runs pyright on pull requests and on pushes to main, a type error is found before or when it reaches main.
Extends: IMPLTS-07-002
IMPLTS-07-010 MUST pyright MUST pass with zero errors.

When a check allows some errors, a new error hides among the old ones. With zero errors as the limit, each new pyright error fails the check, and the contributor who caused it sees it at once.
Extends: IMPLTS-07-002
IMPLTS-07-011 MUST mypy MUST run in CI on every commit to main and on every pull request targeting main.

A type check that runs only on a contributor's machine can be skipped or run on a different scope. When CI runs mypy on pull requests and on pushes to main, a type error is found before or when it reaches main.
Extends: IMPLTS-07-003
IMPLTS-07-012 MUST mypy MUST pass with zero errors.

When a check allows some errors, a new error hides among the old ones. With zero errors as the limit, each new mypy error fails the check, and the contributor who caused it sees it at once.
Extends: IMPLTS-07-003
IMPLTS-07-016 MUST NOT New warnings MUST NOT be introduced after filterwarnings = ["error"] is active.

The suite treats each warning as an error (IMPLTS-07-006), so a change that adds a warning fails the run. The contributor who caused it then fixes it while the cause is clear. A warning left in place often becomes an error at the next dependency upgrade, when nobody remembers its cause.
Derives from: IMPLTS-07-006
IMPLTS-07-017 MUST The project MUST use ruff as its sole Python linter and formatter, configured under [tool.ruff] in pyproject.toml.

One tool for linting, formatting and import order gives one configuration and one set of rules. Two tools that check the same thing can disagree, and a contributor then cannot satisfy both.
Implements: CS-01-001
Implements: CS-02-001
IMPLTS-07-023 MUST The project MUST enforce ruff in its pre-commit hooks and in the CI pipeline.

A pre-commit hook finds a ruff finding before the commit, and CI finds one that a contributor committed without the hooks. ruff checks the whole tree in about a second, so its pre-commit hook costs little on each commit.
Extends: IMPLTS-07-017
IMPLTS-07-024 MUST NOT The project MUST NOT reintroduce Black, flake8 or isort alongside ruff.

CS-15-001 forbids keeping a replaced symbol next to its replacement. This ban applies the same rule to tooling: a second linter or formatter could disagree with ruff, and a contributor then cannot satisfy both.
Derives from: IMPLTS-07-017
IMPLTS-07-018 MUST CI MUST run ruff check and ruff format --check on every commit to main and on every pull request that targets main.

A check that runs on every change keeps the tree clean change by change. A check that runs only now and then lets findings pile up between runs.
Refines: IMPLTS-07-023
IMPLTS-07-026 MUST The CI ruff check and ruff format --check steps MUST fail on any finding.

A finding that CI allows is a finding that nobody fixes. A finding that the project keeps for now carries a # noqa marker with its tracking issue (IMPLTS-07-020), so the zero count does not hide it.
Extends: IMPLTS-07-018

Optional and Prototype Extensions

ID Priority Requirement Related
IMPLTS-06-002 MAY The project MAY use uv for Python environment and dependency management.

uv installs the locked dependencies from uv.lock quickly and the same way on each machine, and the Makefile and CI use it. A MAY keeps an install with pip from pyproject.toml valid for a user who does not have uv.
IMPLTS-06-003 MUST NOT The system MUST NOT carry rdflib or owlready2 as dependencies. The OWL/TTL ontology under ontology/ is retained as a working record and is withheld from the published site, so nothing reads it at runtime or at docs-build time.

rdflib and owlready2 have no use in the code: nothing reads the ontology files at runtime or when the docs build. Each unused dependency adds install time, image size and security updates to every deployed container image. A change that adds either library back must first decide that the ontology is a maintained product, because only then does code need to read it.
IMPLTS-06-004 MAY The system MAY use numpy and pandas for data manipulation and analysis.

The CS state model code (vultron/core/case_states/hypercube/) uses pandas and numpy for table work over the case state space. A MAY lets other analysis code use them too, but it does not require them where plain Python is enough.

Testability

The Vultron inbox handler must be thoroughly testable at unit, integration, and system levels. Testability enables confidence in correctness, supports refactoring, and documents expected behavior.

File ID: TB

Testing Framework

ID Priority Requirement Related
TB-01-001 MUST The system MUST use pytest as the testing framework

One test framework lets one command run every test, in CI and on a developer machine. The suite depends on pytest features: fixtures, markers, pytest-xdist workers and pytest-timeout ceilings (TB-14-001). Tests written for a second framework would need their own runner and could not use these features.
TB-01-002 MUST Test configuration MUST be defined in pyproject.toml

pytest reads its settings from one file. With the markers, the timeouts and the default options in pyproject.toml, a local run and a CI run use the same settings. pytest reads a pytest.ini file before pyproject.toml, so a second file would replace the shared settings.

Test Coverage

ID Priority Requirement Related
TB-02-001 MUST Unit tests MUST achieve 80%+ line coverage

Code that no test runs can break with no test failing. Line coverage shows which code that is. A floor of 80% for unit tests keeps most code under test, and it still permits code that a unit test cannot easily reach.
TB-02-002 MUST Critical paths MUST achieve 100% line coverage

A defect on a critical path, such as message dispatch or a case state change, can corrupt case data or stop the protocol. Full line coverage of these paths makes sure that a change to any of their lines runs at least one test.

Integration Test Coverage

ID Priority Requirement Related
TB-03-001 MUST Integration tests MUST cover inbox POST → handler invocation flow

Unit tests check the parser, the dispatcher and each use case alone. Only a test that posts to the inbox shows that they work together: that a valid activity reaches the correct use case and changes the DataLayer as expected.
TB-03-002 MUST Integration tests MUST cover validation → error response flow

A sender that posts a bad payload needs an error it can act on. An unhandled server error gives no reason, and it looks like a server fault. Only a test through the HTTP stack shows the status and the body that the sender gets.
TB-03-003 MUST Integration tests MUST verify async processing behavior

The inbox answers with HTTP 202 and processes the activity in a background task. A test that checks only the response cannot see that processing. The test must also check the DataLayer after the task ends, or a failure in the task stays hidden.

Test Organization

ID Priority Requirement Related
TB-04-001 MUST Test structure MUST mirror source code structure

When the test tree has the same layout as the source tree, a reader finds the tests for a module at the matching path under test/. A change to a module then shows which tests to run and to update, and a module with no tests is easy to see.
TB-04-002 MUST Test files MUST use descriptive names starting with test_

pytest collects only files whose names match its file patterns, and this repository keeps the defaults, test_*.py and *_test.py. A test file with another name never runs, so its tests can never fail. One prefix for every test file lets a reader find the tests at once, and a descriptive name tells a reader which area a failure is in.
TB-04-003 MUST Unit and integration tests MUST be in separate directories or marked with pytest markers

Integration tests are slower and need more setup than unit tests. The integration marker lets the default options in pyproject.toml leave them out (-m 'not integration'), so the unit suite stays fast. A run with -m "" includes both.

Test Data Management

ID Priority Requirement Related
TB-05-001 MUST The system MUST provide reusable test fixtures

Many tests need the same setup, such as a DataLayer, actors or a case. A shared fixture defines that setup once. Copies of a setup drift apart when the code changes, and the tests that use them then check different things.
TB-05-002 MUST Test data MUST be generated via factories, not hardcoded

Hard-coded test data goes stale when a model gets a new required field or validator, and each copy must then be fixed by hand. A factory builds valid objects in one place, so one change updates every test that uses it.
TB-05-003 SHOULD A test fixture that tests in more than one module share SHOULD be defined in a conftest.py file.

pytest gives every test in a directory, and in the directories below it, the fixtures from that directory's conftest.py, with no import. Shared fixtures kept there are easy to find, so tests do not define the same fixture again. A fixture that only one module uses can stay in that module, next to the tests that read it.
TB-05-004 MUST Tests MUST use proper domain objects, not simplified mock data

Tests with string IDs can pass while production code fails; proper objects exercise actual validation and serialization
TB-05-005 MUST Test semantic types MUST match the activity structure being tested

Semantic type validation is enforced by the use_case_map() key lookup at dispatch time; mismatched tests bypass actual code paths

Test Isolation

ID Priority Requirement Related
TB-06-001 MUST Tests MUST be independent and runnable in any order

A test that depends on another test, or on the order of tests, passes or fails because of the schedule and not because of the code. Under pytest-xdist, the order of tests and the worker that runs each test change between runs. Only independent tests give the same result every time.
TB-06-002 MUST Tests MUST use test database or mocked database

A test that writes to a real deployment's database can change or delete data that is not test data. It can also fail because of data that an earlier run left. A test database or a mock holds only what the test puts in it. The test session sets VULTRON_DATABASE__DB_URL to an in-memory SQLite database by default.
TB-06-003 MUST Test state MUST be reset between tests

State that one test leaves, such as a cached config, a registry entry or blackboard keys, changes what the next test sees. The next test can then pass or fail because of the earlier one. A reset gives each test the same start.
TB-06-004 MUST Test fixtures MUST clean up created data after test completion

Prevents test database bloat and ensures isolation
TB-06-005 MUST Behavior Tree tests MUST clear the py_trees blackboard between tests

py_trees blackboard is a global singleton; without clearing, state from one test leaks into subsequent tests
TB-06-006 MUST All tests MUST be deterministic and produce the same result on every run

Flaky tests erode confidence in the test suite, mask real failures, and slow development. A flaky test that stays in the suite keeps these costs, so only a fix or the removal of the test ends them.
TB-06-007 MUST Integration tests that exercise multi-actor message flows MUST give each simulated actor its own isolated DataLayer instance. Tests that share a single DataLayer across multiple actors bypass the outbox→inbox delivery path and test in-memory state sharing instead of protocol communication.

The outbox→inbox delivery path is a critical protocol boundary. A shared DataLayer removes it: actor A's outbox write is immediately visible to actor B without going through any delivery mechanism, making the test a unit test of shared state rather than an integration test of the protocol.
TB-06-008 MUST A BT factory with probabilistic defaults MUST expose a module-level deterministic factory constant for use in tests. Examples are always-succeed or always-fail stubs for nodes backed by configurable policies.

A test needs a factory that takes one code path every time. A module-level constant gives each test the same one. Convention: name the constant _always_succeed_factory or _always_fail_factory at module level.
Implements: TB-06-006
TB-06-009 MUST A test MUST use the deterministic factory (TB-06-008), not the production random-policy factory.

A test that calls a production BT factory configured with a probability distribution may pass or fail depending on random outcomes. The deterministic factory ensures the test exercises a specific code path every time.
Depends on: TB-06-008

Mocking and Stubbing

ID Priority Requirement Related
TB-07-001 MUST External services MUST be mocked in unit tests

A unit test that calls a real external service depends on the network and on that service. It is slow, and it fails when the service is unavailable. A mock keeps the test about the unit's own logic.
TB-07-002 MUST A unit test MUST reach storage only through a stub or an in-memory SqliteDataLayer (TB-06-002).

A unit test checks the logic of one unit. When that unit reads and writes through a stub or an in-memory store, a failure points at the unit and not at a database deployment, and the test does not depend on database setup. test/conftest.py and BTTestScenario give unit tests a real in-memory SqliteDataLayer.
Refines: TB-06-002
TB-07-003 MAY Integration tests MAY use real database with test data

Some behavior exists only when data is stored: serialization, round trips and queries. An integration test with a real database and test data checks that behavior, which a stub cannot show.

Test Documentation

ID Priority Requirement Related
TB-08-001 MUST Tests MUST use descriptive names explaining what is tested

A test name is the first thing a reader sees when a test fails. A name that states the behavior under test tells the reader what broke without reading the test body.
TB-08-002 SHOULD Complex tests SHOULD include docstrings

A complex test sets up state and checks results that the code alone does not explain. A docstring states the scenario and the expected result, so a reader can tell whether a failure is a defect in the code or a stale test.
TB-08-003 SHOULD Tests SHOULD serve as usage examples

Tests show how to call the code with real inputs, and they fail when the code changes. A test that reads as an example is documentation that stays current, because the test fails when it goes out of date.

Test Maintainability

ID Priority Requirement Related
TB-09-001 MUST Each test function MUST exercise a single scenario.

One scenario per test makes each failure point at one behavior.
TB-09-004 MUST NOT A test body MUST NOT contain conditional branching logic (if/else).

A test with branches checks different things on different runs, and a reader cannot tell which branch ran.
Derives from: TB-09-001
TB-09-005 MUST NOT A test body MUST NOT use a bare try/except block that catches and suppresses an unexpected error. pytest.raises used as a context manager is allowed.

A bare try/except can hide the error the test must report. pytest.raises asserts the one exception the scenario expects and lets every other error fail the test.
TB-09-002 SHOULD Test duplication SHOULD be avoided via fixtures and helpers

Duplicated setup must be changed in every copy when the code changes, and a missed copy tests old behavior. A shared fixture or helper changes in one place (CS-22-001).
TB-09-003 MUST Tests MUST be refactored along with production code

A refactor changes how the code works. A test that is not changed with it either fails, or it passes against code that it does not describe. Changing the tests together with the code keeps the suite a correct description of the code.

Test Infrastructure Consistency

ID Priority Requirement Related
TB-11-001 MUST When a pytest mark is renamed or added, ALL of the following MUST be updated in the same changeset: (a) the markers list in pyproject.toml, (b) any .github/workflows/ YAML files that reference the mark by name (e.g., -m "mark_name" in pytest invocations), and (c) any test files that apply the mark.

When pyproject.toml, a workflow and the test files name a mark differently, a run selects the wrong tests. If a workflow selects by a mark name that no test uses, pytest collects no tests and exits with code 5. CI then fails with "no tests ran", which looks like a problem with the environment, not with a name. A change that updates all three places together prevents this.
TB-11-002 MUST The test job of .github/workflows/python-app.yml MUST run the suite as parallel parts that together collect each test exactly once. Each named part claims paths under test/, and one catch-all part selects test while ignoring every claimed path.

Parts that each list their own paths drop a new test directory in silence: no part selects it, every part reports green, and nothing ran it. A path two parts select runs twice and spends a part's runner time on a result the run already has. Deriving the catch-all from the other parts' claims turns both states into a disagreement between the claims and the ignores, which a check reads off the workflow without running a test.
TB-11-003 MUST The build job and the reporting job of .github/workflows/python-app.yml MUST wait for every test part, so one red part fails the run.

Parts of one matrix job are reached through a single needs: entry, and the needs.*.result aggregate reads failure when any part fails, so the failure notification still files on a push to main. A part moved to its own job id is one a needs: list can omit, and its failure would then neither fail the run nor reach that aggregate.
Refines: CISEC-05-013

BT Test Harness

ID Priority Requirement Related
TB-12-001 MUST BT leaf and composite node tests MUST use the BTTestScenario harness in test/core/behaviors/bt_harness.py.

BTTestScenario runs a node through the real BTBridge steps (setup, initialise, update and shutdown) with the acting actor's own DataLayer. A test that builds the blackboard by hand can give a node state that the real tree never gives it. Such a test can pass while the node fails in production.
TB-12-002 MUST Each BT scenario test MUST run the BT tree exactly once per test case.

A tree instance keeps its blackboard state and node statuses after a run. A second run of the same instance starts from that state, so it can pass because of what the first run left, and that accumulated state masks isolation failures.
Extends: TB-12-001
TB-12-007 MUST Each BT scenario test case MUST get a fresh tree instance.

A fresh tree for each test case starts every run from the same state, with no blackboard state or node status left by another test case.
Extends: TB-12-002
TB-12-003 SHOULD A BT integration test SHOULD complete within 5 seconds of honest work per test case on an idle machine.

This is a design budget that keeps BT scenarios small, not a ceiling. The per-test timeout tiers (TB-14-001) sit well above it so that load on a CI runner or dev box never trips them on honest work, which means no timeout enforces this budget.
TB-12-004 SHOULD When a BT scenario's root Sequence fails, the test SHOULD assert the status of each leaf, not only the root status.

A Sequence with memory=True reports FAILURE when any child fails, also when the children before it succeeded. A root status alone does not show which children succeeded and which failed, so a test can pass with the wrong child failing. Leaf statuses show where the tree stopped.
Extends: TB-12-001
TB-12-005 SHOULD A BT test that exceeds the TB-12-003 budget SHOULD be redesigned (e.g., reducing dataset size, mocking external I/O) rather than given its own longer @pytest.mark.timeout.

A per-test override hides a slow scenario from the budget it breaks. Redesigning the test keeps the scenario small. A timeout tier that fires on honest work across many tests is a different problem, covered by TB-14-003.
Uses definition from: TB-12-003

Architecture Ratchet Corpus

ID Priority Requirement Related
TB-13-001 MUST All architecture ratchet tests in test/architecture/ that scan the source tree MUST obtain file paths and source text from a shared module-level corpus helper (test/architecture/_corpus.py) rather than calling pathlib.Path.rglob or reading files directly.

Each architecture test scans the source tree. If each test reads and parses the files itself, the suite pays that cost once per test, and the cost grows with each new test. test/architecture/_corpus.py reads the files once, when the module is imported, and every test uses that copy. Module import happens at collection, outside the per-test timeout (TB-14-001).
TB-13-002 MUST Architecture ratchet tests MUST apply a substring prefilter before calling ast.parse().

ast.parse() costs much more per file than a substring check. Most files cannot match a given architecture test, because they do not contain the module path or the name that the test looks for. A substring check first lets the test parse only the files that can match.
Extends: TB-13-001
TB-13-003 MUST NOT A file in test/architecture/ other than _corpus.py MUST NOT call ast.parse() or pathlib.Path.rglob directly.

Without this rule, a new architecture test can read or parse files on its own and bring back the cost that the shared corpus removes. _corpus.py is the shared corpus helper (TB-13-001), so it is the one file that reads and parses.
Refines: TB-13-001
TB-13-009 MUST A meta-ratchet in test/architecture/test_ratchet_hygiene.py MUST fail when any sibling file contains a bare ast.parse( or .rglob( call outside _corpus.py.

A rule with no check is broken without notice. The meta-ratchet searches the source text for those strings and parses nothing, so it obeys the rule it checks.
Verifies: TB-13-003
TB-13-004 SHOULD Each architecture ratchet test SHOULD finish within 0.5 seconds on an unloaded host, not counting a shared code analysis it reuses. Building that shared analysis, or a test that builds one for itself, gets 10 seconds.

The unit suite runs every architecture test, so a slow one slows each run. The shared corpus (TB-13-001) and the substring check (TB-13-002) keep an ordinary test under 0.5 seconds. A shared code analysis (a cached derivation that parses a few hundred modules) costs seconds, paid once per process or by the one test that builds it; the heaviest measured about 5 seconds (#5896). Its module states the measured cost. The per-test timeout (TB-14-001) does not enforce either tier.
TB-13-006 MUST A test that relies on shared global state MUST reset that state or carry an xdist_group mark shared with the tests that change it. Shared global state includes the py_trees blackboard and module-level singletons.

pytest-xdist runs tests on several workers, in an order that changes between runs. A test that depends on global state that another test changed then fails at random (TB-06-006). A reset, such as the autouse fixture in test/conftest.py that clears the py_trees blackboard, removes the dependency. An xdist_group mark, which --dist loadgroup obeys, keeps tests that must share state on one worker.
Refines: TB-06-001
TB-13-008 MUST NOT Architecture ratchet tests MUST NOT call ast.parse() on files that do not contain the target fragment string as a plain substring.

ast.parse() is the dominant per-file cost (~1 ms each); calling it on non-matching files wastes CI time proportional to corpus size.
Refines: TB-13-002

Test Run Timeouts

ID Priority Requirement Related
TB-14-001 MUST Every test MUST run under a per-test pytest-timeout ceiling configured in pyproject.toml, with a wider tier applied at collection time to every integration-marked test.

A ceiling turns a hung test into a named failure. Integration tests do more honest work under a wider spread of load, so one ceiling for both is either too tight for one or too loose for the other. The tier depends on the integration marker that directory hooks add, so it is applied after them.
TB-14-007 MUST A test's own @pytest.mark.timeout MUST override the integration timeout tier (TB-14-001).

Some tests need a ceiling that differs from their tier, such as the demo suite's deliberate values. The tier is a default, so a test that sets its own ceiling keeps it.
Supersedes: TB-14-001
TB-14-002 MUST A per-test timeout trip MUST fail only the test that tripped it.

A trip that ends the process fails every test that has not run yet. Under pytest-xdist the ended process is a worker, which TB-14-004 must then handle. The signal timeout method meets this; the thread method does not.
Extends: TB-14-001
TB-14-008 MUST After a per-test timeout trip, the session MUST go on with the remaining tests.

A session that stops at a trip never runs the tests after it, so a red run gives no signal about them.
Extends: TB-14-002
TB-14-009 MUST After a per-test timeout trip, the session summary MUST name every failure.

A trip that ends the process loses the names of failures already recorded. The summary must name them all, or a reader cannot tell what to fix.
Extends: TB-14-002
TB-14-003 SHOULD A timeout tier that fires on honest work across its tests SHOULD be raised, not each test given its own @pytest.mark.timeout or recorded as flaky. One outlier test is TB-14-011's case.

A ceiling is a hang detector, not a performance budget. Contention on CI runners and loaded dev boxes inflates honest tests far past their idle cost, and a too-tight tier reads as flakiness that is re-diagnosed again and again.
Uses definition from: TB-14-001
TB-14-011 SHOULD A single test that trips its timeout tier on honest work SHOULD be made faster. A per-test @pytest.mark.timeout is a stopgap whose comment names the issue that will remove it.

The tier is the hang detector for every other test it bounds. Raising it for one outlier makes every hang hold a worker longer, so the cheapest fix for the whole suite is to speed up the outlier, for example by sharing work it repeats. A marker with no named issue becomes a permanent exemption that nobody revisits.
Refines: TB-14-003
TB-14-004 MUST When a worker process dies, a pytest-xdist run MUST fail and name the test the worker was running.

A dead worker is a fault the run must report. The name of the test it ran shows where to look.
TB-14-010 MUST NOT A pytest-xdist run MUST NOT wait for a replacement worker to finish a dead worker's tests.

Under --dist loadgroup xdist re-queues a dead worker's finished work units as well as its unfinished ones, and a replacement worker handed a unit with nothing to run never reports, so the run waits forever. --max-worker-restart=0 in addopts stops the replacement.
Extends: TB-14-004
TB-14-005 MUST Every local gate command written for agents, and the CI test job, MUST run under a wall-clock ceiling, so that a hang no per-test timeout can reach ends the run with a known exit status.

A signal-based per-test timeout cannot interrupt a C call that holds the GIL, and a stuck xdist controller runs no test at all. Without an outer ceiling such a run waits until the agent's tool timeout or GitHub's job default. Agents run in the Linux devcontainer. Human how-to pages under docs/developer/ keep the bare command, because stock macOS has no timeout.
TB-14-006 MUST Every job in every workflow under .github/workflows/ MUST declare timeout-minutes, set well above the job's observed run time. A job that calls a reusable workflow is exempt; the called workflow's jobs carry the cap.

A job with no cap runs until GitHub's default limit, so a hung linter or build step holds a runner for hours and shows as cancelled rather than failed. A cap well above the observed run time ends a hang within minutes without tripping on honest work under load. Scheduled and issue-triggered jobs hang the same way and nobody watches them, so the rule covers every workflow, not only the PR gates. GitHub rejects timeout-minutes on a job that calls a reusable workflow, hence the exemption.
Refines: TB-14-005

Test Starting Points on the Scenario Tree

ID Priority Requirement Related
TB-15-001 MUST A multi-actor integration test MUST start from a named starting point, a declared step on a demo scenario path.

Sibling tests that replay the same steps to reach their starting state pay for those steps again and test them again. A run per commit on hundreds of pull requests a week makes that cost real. One tree for demos and tests means each case state is defined once.
Uses definition from: DEMOCI-11-014
TB-15-002 MUST The test harness MUST run the steps that reach a named starting point once per test session, when it builds that point. Under parallel test workers, a session is one worker's run.

A test then pays only for its own acts. The test that takes a step from one starting point to the next is the one test that exercises that step.
Uses definition from: TB-15-001
TB-15-003 MUST The test harness MUST build each named starting point with the seeded id source and clock that the scenario recordings use.

Every copy is then identical on every run. A copy whose ids or timestamps vary between runs makes the tests that load it nondeterministic (TB-06-006). Sharing the recordings' seeding keeps a starting point and the recording of the same step comparable.
Uses definition from: TB-15-001
TB-15-004 MUST The ledger rebuild check MUST prove a named starting point rebuilds from its ledger once, when the point is built.

Replaying the starting point's whole ledger after every test that loads it re-checks steps already checked.
Uses definition from: TB-15-002
TB-15-005 MUST For a test that loads a named starting point, the ledger rebuild check MUST replay only the test's own entries. It replays them onto the point's rebuilt store.

The point's own entries were proven once (TB-15-004), so replaying only the test's entries on top of the rebuilt point still covers the whole chain.
Depends on: TB-15-004
TB-15-006 SHOULD A test of a state no scenario path reaches SHOULD load the nearest named starting point and then apply its own change.

A diverged replica or a forced commit failure is not a story, so no declared step reaches it. Building a whole case outside the ledger for it repeats setup the tree already provides.
Refines: TB-15-001
TB-15-007 MUST A test that loads a named starting point MUST get its own copy of each actor's store at that point.

A shared store would let one test's writes change what another test starts from. Copies keep each test independent (TB-06-001, TB-06-003).
Uses definition from: TB-15-001

Guard Reachability

ID Priority Requirement Related
TB-16-001 MUST A private guard under vultron/ — an undecorated, single-underscore, non-dunder definition that raises in its own scope — MUST be referenced from production code under vultron/.

A guard nothing names cannot run, so no test of it can fail for a real reason. Unlike missing coverage, which a coverage report shows as a gap, a green direct-call test reports the requirement as covered: the spec-coverage ratchet counted CLP-14-002, CLP-14-003 and CLP-14-006 as covered while the guard implementing them had never executed.
TB-16-002 MUST Where a parameter defaulting to None gates a refusal, some call site under vultron/ MUST supply that parameter.

A caller alone is not enough. _validate_canonical_entry had a production caller; what it did not have was a caller that passed case_published, and the CLP-14-013 check sat behind if case_published is not None:. A gate no caller opens is a check that never runs, however many tests call the guard directly.

Strict Goal Markers

ID Priority Requirement Related
TB-17-001 MUST An xfail marker on a test under test/ MUST be written with strict=True. A marker in a pytest.param(marks=...) entry counts the same as a decorator. The one exception is a file recorded, with its reason, in the pinned exemption set the enforcing check reads.

An xfail here marks a goal state: a requirement written before the code that satisfies it. Under strict=False the day that code lands is an XPASS in a tally nobody reads, so the marker outlives its defect and the assertion it guarded stops being checked (#3934 item 2, #2244). ARCH-21-008 asks the same, but as a SHOULD and only of an ARCH-21-005 backlog's goal test, so the broader rule several prose statements assert had no requirement behind it, and its check would read as unfounded.

Specification Traceability

Requirements for the story graph: the generated traceability matrix and index table that map user stories to specification requirements, the integrity of the story-page catalog they enumerate, and the report of the protocol requirements with no story.

File ID: TRACE

Traceability Matrix

ID Priority Requirement Related
TRACE-01-001 MUST A traceability matrix exists at docs/reference/user_stories/traceability.md holding one entry per story page in docs/reference/user_stories/. Each entry lists the requirements that name that story in their stories: field, grouped by spec file. Each requirement links the page that renders its row.

Without one map from stories to requirement IDs, nobody can tell which user needs the specs cover. Nobody can tell which stories a requirement change affects. The map is in the docs tree, so it is published next to the stories that it describes.
TRACE-01-002 MUST A user story that no requirement names in a stories: field is flagged in both the traceability matrix and the index table. The flag is an explicit note stating that the story has no mapped requirements.

An unmapped story looks the same as a story that nobody checked. An explicit note shows a known gap, not an error by omission, and a search can find the note.
TRACE-01-003 MUST The committed traceability matrix agrees with the stories: fields in specs/ and with the story-page catalog, and a check mode fails when it does not.

A matrix that disagrees with the spec files shows coverage that was removed, or hides coverage that was added. Hand maintenance is how the matrix came to link 161 of the 801 requirements that carried a story. A check mode makes disagreement a failure in the change that causes it, rather than a discovery months later.

Maintenance

ID Priority Requirement Related
TRACE-02-001 SHOULD A change to a requirement's stories: field, or to the story-page catalog, SHOULD regenerate the committed matrix and index table in the same change.

The generated artifacts are committed, so a change that leaves them stale fails the next check mode for whoever touches them next instead of for its own author. Regenerating costs one command while the author still holds the context.
TRACE-02-002 SHOULD A story that names a need no requirement serves, and that no open issue tracks, SHOULD be recorded as a type:Idea issue filed through create-issue.

The matrix already flags every story no requirement cites (TRACE-01-002), so a second record of the same fact can only disagree with it. A flag shows only that coverage is missing, not what to do. An issue can be assigned, scheduled and closed, which a learning file cannot (BW-01), so the need reaches a person who can plan it. A story whose disposition waits on a scope decision, or whose citing work is already scheduled, needs no new record.

Story Graph Generation and Catalog Integrity

The story graph has two sides: a requirement's stories: field in specs/, which ADR-0072 made authoritative, and the story pages under docs/reference/user_stories/. This group holds the edges between them sound — a cited page exists and is never removed — and makes the artifacts that display the graph derived rather than hand-kept.

ID Priority Requirement Related
TRACE-03-001 MUST The spec linter reports as a hard error each stories: entry naming a story that has no page under docs/reference/user_stories/. The error names the citing requirement and every absent story ID, and no lint_suppress code silences it.

Checking only the ID pattern lets a typo pass as a citation that resolves to nothing: the matrix cannot show the edge, and a reader cannot reach the need the requirement claims to serve. Unlike "this requirement has no story", which can be true, a citation that resolves to no page is always a mistake, so there is nothing for a suppression to express.
Uses definition from: SR-11-001 — Checks the stories: field SR-11-001 defines; SR-11-002 checks the shape of the ID, this checks that it resolves.
TRACE-03-002 MUST NOT A pull request MUST NOT remove a story page from docs/reference/user_stories/. A story that is withdrawn, split or replaced keeps its page, which names the story IDs that supersede it.

A stories: entry must resolve for as long as any revision of the citing spec exists, and a removed page is also a freed ID that a later story could reuse, silently repointing every citation of the old one. Keeping the page costs a file and makes reuse impossible.
TRACE-03-003 MUST This codebase generates both docs/reference/user_stories/table.md and docs/reference/user_stories/traceability.md from the requirement registry's stories: fields and the story-page catalog, gated by a check mode, not by hand. The table's third column states each story's coverage, the number of requirements that cite it.

The spec files are the authoritative side of the story graph (ADR-0072), so an artifact that displays the graph is derivable and a hand-kept one can only drift. The column the coverage replaces held a support level assigned once against v0.4.0, which no check could keep true and which nine of the eleven out-of-scope stories already contradicted.
Implements: TRACE-01-001
TRACE-03-004 MUST This codebase reports every kind: protocol requirement with no stories: entry, grouped by spec file and then by priority, marking each requirement that carries lint_suppress: [missing_story_reference]. By default the report prints one summary line per spec file. A selector narrows it to a spec file or a requirement-ID prefix.

Closing the protocol story gap is worked one spec-file area at a time, so each area needs its own worklist. The hand-written lists that preceded this report were measured once, and a third of the IDs on them had been relabelled or retired before anyone read them; a list derived from the registry on each run cannot go stale that way.

Triggerable Behaviors

Requirements for the trigger API that allows an actor to initiate protocol behaviors based on its own internal state, rather than reacting to an inbound ActivityStreams message. Triggerable behaviors are the outgoing counterpart to the inbound handler pipeline and are required to demonstrate the full CVD protocol.

File ID: TRIG

Endpoint Format

ID Priority Requirement Related
TRIG-01-001 MUST The system MUST expose trigger endpoints using the path pattern POST /actors/{actor_id}/trigger/{behavior-name}

The path names the actor and the behavior, so a client does not need to learn a different route for each verb. The server takes the actor only from the path, never from the body. Thus each request names one actor in one place.
TRIG-01-002 MUST Trigger endpoints MUST return HTTP 202 on successful acceptance

The behavior runs after the server sends the response (TRIG-01-004). Thus the server can confirm only that it accepted the request, not that the behavior is complete. A 202 response states exactly this, and the inbox uses the same code (IE-05-001).
TRIG-01-003 MUST Trigger endpoints MUST return a structured error response when the actor, case, or report referenced in the request body cannot be resolved

A request that names an actor, case or report that the server does not hold cannot succeed. When the server refuses it in the response, the caller knows the problem immediately. A 202 response would hide the failure in a background task that the caller cannot see.
Uses definition from: EH-05-001
TRIG-01-004 MUST NOT Trigger endpoint processing MUST NOT block the HTTP response.

A behavior tree run and its outbox delivery can take much longer than an HTTP client waits. If the server held the response, each call would use a server worker for that time. A caller timeout would also look like a failed behavior. Thus the trigger sends the response first and runs the behavior after it, as the inbox does (IE-05-002).
TRIG-01-005 MUST A trigger endpoint MUST run long-running behavior execution as a background task.

A background task lets the endpoint answer before the behavior tree and its outbox delivery finish. The server worker is then free, and a caller timeout does not look like a failed behavior (IE-05-002).
Implements: TRIG-01-004

Candidate RM Behaviors

ID Priority Requirement Related
TRIG-02-001 SHOULD The following RM behaviors SHOULD be individually triggerable via the trigger API: validate-report, invalidate-report, reject-report, submit-report, ack-report

Each of these steps is a decision that an actor makes about a report. A person or an agentic client must be able to make that decision through the behavior tree of the actor. When a case holds a report, the case refuses Reject(Offer(VulnerabilityReport)) from all senders (CM-23-019, ADR-0144). An actor closes its part when it leaves the case (TRIG-13-001). Thus no report trigger closes a report that a case holds. To close a report that no case holds, an actor uses reject-report (ADR-0145).
TRIG-02-002 SHOULD The following EM behaviors SHOULD be individually triggerable via the trigger API: propose-embargo, accept-embargo, reject-embargo, propose-embargo-revision, terminate-embargo

Each embargo step is a decision that an actor makes. A person or an agentic client must be able to make that decision without building activities by hand. One trigger for each step gives each decision its own entry point and its own request checks.
TRIG-02-003 SHOULD The following CS state-notification behaviors SHOULD be individually triggerable via the general-purpose trigger API (TRIG-08-003): notify-fix-ready, notify-fix-deployed, notify-published, notify-public-exploit, notify-attacks-observed. notify-published records that the actor has become Public Aware (it has learned the vul is public, by whatever means); it does not assert that the actor published anything.

An actor learns each of these facts in one of two ways. An outside party tells it: a person or a tool invokes the trigger. Or the behavior tree of the actor asks an outside source through a call-out point (for example, DevelopFixCallOutBundle.create_fix_factory). Both ways are correct in production. Thus these triggers are general-purpose triggers (TRIG-08-002), not demo-only triggers.
Uses definition from: TRIG-08-003
TRIG-02-004 SHOULD The following case management behaviors SHOULD be individually triggerable via the trigger API: engage-case, defer-case, leave-case, add-object-to-case, create-case, add-report-to-case

An actor makes its own decision to engage, defer, leave or add to a case. A client needs one entry point for each decision. Then each decision runs the behavior tree of the actor, not an activity that someone built by hand.
TRIG-02-005 SHOULD The following participant management behaviors SHOULD be individually triggerable via the trigger API: suggest-actor-to-case, accept-case-invite, reject-case-invite, invite-actor-to-case, accept-actor-recommendation, reject-actor-recommendation

Invitations, suggestions and answers to invitations decide who takes part in a case. This is an actor decision. One trigger for each step lets a client make each decision through the behavior tree of the actor. That tree applies the role checks and the addressing checks.
TRIG-02-006 MUST The add-note-to-case and sync-log-entry triggers MUST be classified demo-only (TRIG-08-002).

Production needs neither verb. A correct implementation commits a SYNC entry each time the state changes. Thus sync-log-entry only lets a demo script insert entries by hand (TRIG-10-004). add-note-to-case is a shortcut for add-object-to-case, which already adds a Note (TRIG-10-003). Leaving a case is an actor decision, not a demo step that a script controls. Thus it is the general-purpose leave-case trigger (TRIG-13-001), not a demo verb (ADR-0145).
Uses definition from: TRIG-08-002
TRIG-02-007 SHOULD Actors holding the CASE_OWNER role SHOULD be able to trigger the following role delegation behaviors via the trigger API: offer-case-manager-role, offer-case-participant-role, offer-case-ownership-transfer, accept-case-ownership-transfer.

Only the Case Owner can delegate its roles or transfer the case. Thus the Case Owner needs an entry point for each delegation step. Without one, the only way to delegate is to build the Offer or the Accept by hand. That skips the behavior tree of the owner.

Request Body

ID Priority Requirement Related
TRIG-03-001 MUST A trigger request body for a case-scoped behavior or an offer response MUST include the id of that case or offer. The case id is case_id. The offer id is offer_id, or cp_offer_id for an answer to an actor recommendation.

A case-scoped behavior with no case id has nothing to act on. An offer response with no offer id also has nothing to act on. When the request schema requires the id, the server refuses a call that cannot run, before it queues anything. Other triggers name their target by another field, which the API schema defines: submit-report names its recipient_id, create-case an optional report_id, and each answer to a case invite its invite_id.
TRIG-03-002 MUST Unknown fields in the request body MUST be ignored (forward-compatibility)

A client built for a newer API can send fields that this server does not know. When the server ignores them, that client continues to work with an older server. The server still validates the fields that it knows.
TRIG-03-003 SHOULD The trigger endpoint request body SHOULD support an optional note field containing free-text content that will be embedded in the outgoing ActivityStreams activity (e.g., rationale for embargo proposal, reason for deferral)

The recipients of an activity see only what the activity carries. A free-text note lets the acting party tell them why it acted, for example the reason for a deferral. A CVD decision often needs this reason, and no structured field holds it.
TRIG-03-004 MUST The reject-report trigger request body MUST include a note field that gives the reason.

Hard-close decisions are irreversible and warrant documented justification for audit purposes
Refines: TRIG-03-003
TRIG-03-005 SHOULD The note value of a reject-report trigger request SHOULD be non-empty.

An empty note satisfies the field but records no reason. A hard close cannot be undone, so an audit needs the reason the note gives.
Extends: TRIG-03-004

Response Body

ID Priority Requirement Related
TRIG-04-001 SHOULD A successful trigger response SHOULD include the resulting ActivityStreams activity in the response body under an activity key:

The caller often needs the exact activity that the actor sent. The caller can show the activity, audit it, or name it in a later call, for example the proposal that a withdrawal names (TRIG-11-006). When the response contains the activity, the caller does not need a second lookup, and the response states what the actor sent.
TRIG-04-002 MAY When a trigger initiates a long-running behavior, the response MAY return a job object per AR-04-001 instead of the activity directly

A behavior that runs for a long time cannot return its activity in the response, because the activity does not exist yet. A job object gives the caller an item that it can poll to get the result.
Uses definition from: AR-04-001
TRIG-04-003 MUST When a triggered behavior terminates because it emitted an authorization request rather than completing the requested action, the trigger response MUST identify the request it emitted.

A trigger returns 202 and runs the behavior in the background. Without more data, a caller cannot tell "done" from "waiting for the decision of a different party". Under ASK-01-006, success means that the actor sent the request, so success alone has two meanings. When the response names the request, the caller can find the outcome in the outstanding-ask collection (ASK-04-009).

BT Integration

ID Priority Requirement Related
TRIG-05-001 SHOULD Trigger endpoint implementations SHOULD reuse existing BT trees rather than duplicating behavior logic

The same behavior can start from a trigger or from a received message. When both entry points use one tree, their checks and effects cannot become different (CS-22-001).
TRIG-05-002 SHOULD The trigger endpoint SHOULD invoke the BT tree via the bridge layer (vultron/core/behaviors/bridge/) using the same pattern as existing BT-using handlers

The bridge is the only place that sets up the blackboard and DataLayer of a tree, ticks the tree, and reads its result. When trigger trees run through the bridge, they get the same execution and error handling as received trees. Then there is no second runner to keep the same as the first.
Depends on: BT-05-001

Per-Actor DataLayer

ID Priority Requirement Related
TRIG-06-001 MUST Trigger endpoints MUST resolve the correct per-actor DataLayer instance using the actor_id path parameter

Trigger endpoints are this codebase's local REST surface for driving its own actors, not messages between implementations, and per-actor stores are how this codebase isolates them (ADR-0073). Only this codebase must obey it, so it is project (ADR-0134).
Implements: CM-01-001
TRIG-06-002 MUST Trigger endpoint implementations MUST accept the DataLayer instance via dependency injection to allow per-actor isolation to be retrofitted without changing endpoint contracts

Tests and alternative deployments replace the store through the dependency, not through the endpoint. With injection, the way the server resolves a store can change, and the routes that clients call do not change.

Outbox Activity

ID Priority Requirement Related
TRIG-07-001 MUST A successfully executed trigger MUST produce an outgoing ActivityStreams activity added to the actor's outbox

A trigger exists so that the actor can tell a different party something. The outbox is the only way that an activity leaves the actor (OX-02-001). If a run reports success and the outbox is empty, the caller thinks that the actor sent a message, but the actor did not.

Trigger Classification

ID Priority Requirement Related
TRIG-08-001 MUST The application MUST define a RunMode StrEnum with at least two values: PROTOTYPE and PROD

The server mode decides whether demo-only routes exist, so the mode must be one named setting. With a closed enum, a misspelled or undefined mode is a validation error, not a silent fallback.
TRIG-08-002 MUST A trigger is general-purpose if it represents either a legitimate external stimulus (e.g., a finder submitting a report) or an intentional actor decision that a human operator or agentic client might initiate (e.g., validating a report, proposing an embargo). A trigger is demo-only if the only reason it exists is to let a demo script puppeteer an actor through a step the actor's own BT would handle autonomously in a real deployment.

A demo-only trigger makes an actor do a step that its own behavior tree would do. In production, such a trigger would let a caller override the actor. The definitions give each verb a test that a reviewer can check, and the test decides whether production can expose the verb.
TRIG-08-003 MUST General-purpose triggers MUST be exposed under the path prefix /actors/{actor_id}/trigger/{behavior-name} (TRIG-01-001)

One prefix for production triggers gives clients one place to find them. It also makes the production surface equal to all routes under that prefix.
Refines: TRIG-01-001
TRIG-08-005 MUST This codebase MUST store RunMode as the top-level field AppConfig.mode, set by VULTRON_MODE, with a default of RunMode.PROTOTYPE.

All run-time settings are in one configuration model (CFG-04-001), so the mode is set in the same place as all other settings. The mode decides which routes the server mounts, not how the server runs, so it sits beside server: rather than inside it. The default is PROTOTYPE because this codebase runs as a prototype, and its demos need the demo routes with no extra setup.

Demo Trigger Endpoints

ID Priority Requirement Related
TRIG-09-001 MUST Demo-only trigger endpoints MUST use the URL path pattern POST /actors/{actor_id}/demo/{behavior-name}

Demo routes and general-purpose routes (TRIG-08-003) are different only in one path segment. Thus demo scripts and clients use the same call shape for both, and that segment alone shows the kind of call. The separate prefix also lets the server mount or omit the demo routes as one group (TRIG-09-002).
TRIG-09-002 MUST The FastAPI application MUST include the demo router only when get_config().mode == RunMode.PROTOTYPE.

Demo-only verbs move an actor through steps that it would do by itself. If a production server mounted them, any caller could make an actor do a step in place of its own behavior tree. A caller cannot call a route that the server does not mount.
TRIG-09-003 MUST When get_config().mode == RunMode.PROD, any request to a path under /demo/ MUST return HTTP 404 (the routes are not mounted; no custom error message is required)

A production server must not show that demo controls exist. When the routes are not mounted, the server returns the same 404 as for any unknown path. No special handler is necessary, so no special handler can be wrong.
Derives from: TRIG-09-002
TRIG-09-004 MUST Demo trigger endpoints MUST share the same per-actor DataLayer injection pattern as general-purpose trigger endpoints (TRIG-06-001, TRIG-06-002)

A demo trigger acts on the same actor store as the real triggers of that actor. A different injection path could resolve a different store, and the test override that replaces the real store would not replace it.
Refines: TRIG-06-001
Refines: TRIG-06-002
TRIG-09-005 MUST Demo trigger endpoints MUST use an OpenAPI tag that visually distinguishes them from general-purpose triggers in the Swagger UI (e.g., tags=["Demo Triggers"] vs tags=["Triggers"])

A reader of the API documentation must be able to identify the endpoints that are demo controls, which a production server does not have. The reader must know this before writing a client that depends on them.

Generalized Object Triggers and Type-Specific Wrappers

ID Priority Requirement Related
TRIG-10-001 MUST The system MUST expose an add-object-to-case general trigger at POST /actors/{actor_id}/trigger/add-object-to-case that accepts any object type the protocol routes as Add(object)[target=VulnerabilityCase]. The exceptions are the types whose addition the protocol carries by its own flow: EmbargoEvent, CaseParticipant and CaseStatus.

Adding content to a case is a legitimate operator action for more than one object type. A Note is the most common use, but not the only one. An embargo proposal is an Invite relayed by the CASE_MANAGER (EP-09-001), and participants and status changes have role-gated flows of their own, so those types are not part of this trigger. Add(EmbargoEvent)[target=VulnerabilityCase] is the Case Owner's activation, sent only by the owner-decision paths (the accept-embargo trigger and the owner's automatic answer) with a required inReplyTo (ADR-0180).
TRIG-10-002 MUST Type-specific convenience triggers (e.g., add-report-to-case) MUST delegate to the corresponding general trigger after performing type-specific validation

The general trigger holds the routing check and the CASE_MANAGER addressing (TRIG-10-001). A wrapper that sent its own Add would skip that refusal. The wrapper could then queue an Add that the CASE_MANAGER drops, and still tell the caller 202.
TRIG-10-003 MUST NOT This codebase MUST NOT expose add-note-to-case as a general /trigger/ endpoint.

add-object-to-case already adds a Note to a case. A second production path for the same act would need its own checks. These checks must stay the same as the checks of the first path. Only demo scripts use the note shortcut, so the shortcut is in the demo layer.
Derives from: TRIG-02-006
TRIG-10-004 MUST NOT This codebase MUST NOT expose sync-log-entry as a general /trigger/ endpoint.

In a correct implementation, SYNC log entries are committed automatically as a cascade effect of every state-changing operation. An explicit trigger exists only to let the demo script inject entries manually. A future production "force-sync" recovery operation would require a protocol-level mechanism for a peer to advertise its current log tail hash before entries are replayed (SYNC-17-001, SYNC-18-001)
Derives from: TRIG-02-006
TRIG-10-005 MUST The add-object-to-case trigger MUST refuse with HTTP 422, queuing nothing, an object whose Add no receive-side pattern matches or whose type TRIG-10-001 excepts.

The Add is a participant's request to the CASE_MANAGER (PCR-08-005). An object type that the CASE_MANAGER cannot route would be dropped on arrival while the caller was told 202. An EmbargoEvent, a participant or a status has a role-gated flow of its own, and a general Add would bypass its gates.
Extends: TRIG-10-001
TRIG-10-006 MUST This codebase MUST serve add-note-to-case at /demo/add-note-to-case, as a demo-only convenience wrapper around add-object-to-case.

Demo scripts use the note shortcut, so it needs a route. Under /demo/ it is not mounted in production (TRIG-09-002), and as a wrapper it reuses the checks of add-object-to-case (TRIG-10-002).
Extends: TRIG-10-003
TRIG-10-007 MUST This codebase MUST serve sync-log-entry at /demo/sync-log-entry.

Demo scripts use the route to inject SYNC log entries by hand. Under /demo/ it is not mounted in production (TRIG-09-002), where entries commit as a cascade effect of each state change.
Extends: TRIG-10-004

Case Ownership Transfer Triggers

ID Priority Requirement Related
TRIG-11-001 MUST The system MUST expose an offer-case-ownership-transfer trigger at POST /actors/{actor_id}/trigger/offer-case-ownership-transfer that accepts a case_id and transferee_id in its request body and emits the requesting Case Owner's proposal, Offer(Offer(VulnerabilityCase)), to the case's CASE_MANAGER, which offers the case to the specified transferee (CM-21-005). The response's activity is the proposal.

Without this trigger, demo scripts must inject ownership-transfer offers directly into the transferee's inbox, which bypasses the offering actor's BT execution and violates DEMOMA-05-001. A trigger endpoint ensures the full hexagonal stack is exercised for both sides of the handshake.
Refines: TRIG-01-001
Extends: TRIG-02-004
Uses definition from: CM-21-005
TRIG-11-002 MUST The system MUST expose an accept-case-ownership-transfer trigger at POST /actors/{actor_id}/trigger/accept-case-ownership-transfer that accepts an offer_id in its request body and emits an Accept(Offer(VulnerabilityCase)) (ownership transfer variant) from the requesting actor, addressed to the CASE_MANAGER (CM-21-006).

Symmetry with TRIG-11-001: the accepting actor must also be puppeteered through a trigger so that its BT execution is exercised, consistent with DEMOMA-05-001.
Refines: TRIG-01-001
Extends: TRIG-02-004
Refines: CM-21-006
TRIG-11-003 SHOULD The offer-case-ownership-transfer trigger request body SHOULD accept an optional content field (free-text message) to include in the offer activity, consistent with the factory function signature for offer_case_ownership_transfer_activity.

The Case Owner can tell the transferee why it offers the case. The trigger uses the parameter of the factory function, so it passes the text through and needs no mapping of its own.
Extends: TRIG-11-001
TRIG-11-004 MUST Every ownership-transfer trigger MUST return the emitted ActivityStreams object in the activity field of its response body.

TRIG-04-001 recommends this response shape for every trigger, and TRIG-04-002 lets a long-running trigger return a job object instead. A transfer trigger makes the shape binding because a later step names the activity that it sent: a withdrawal names the proposal of the owner (TRIG-11-006). When the response returns the activity in activity, the caller gets that id without a second lookup.
Refines: TRIG-04-001
Extends: TRIG-11-001
Extends: TRIG-11-002
Extends: TRIG-11-005
TRIG-11-005 MUST The system MUST expose a reject-case-ownership-transfer trigger at POST /actors/{actor_id}/trigger/reject-case-ownership-transfer that accepts an offer_id in its request body and emits a Reject(Offer(VulnerabilityCase)) (ownership transfer variant) from the requesting actor, addressed to the CASE_MANAGER (CM-21-010).

Symmetry with TRIG-11-002. Without it the only way to decline a transfer is to build the Reject by hand and post it into the CASE_MANAGER's inbox, which is what the transfer-ownership exchange demo does and DEMOMA-05-001 forbids.
Refines: TRIG-01-001
Refines: CM-21-010
TRIG-11-006 MUST The system MUST expose a withdraw-case-ownership-transfer trigger at POST /actors/{actor_id}/trigger/withdraw-case-ownership-transfer that accepts an offer_id in its request body, naming the requesting Case Owner's own proposal (the activity TRIG-11-001 returned), and emits Undo(Offer(Offer(VulnerabilityCase))) of that proposal, addressed to the CASE_MANAGER (CM-21-015).

Symmetry with TRIG-11-002 and TRIG-11-005: the offerer withdraws through a trigger, so the withdrawal runs the same behavior tree a real client would (DEMOMA-05-001).
Refines: TRIG-01-001
Uses definition from: TRIG-11-001
See also: CM-21-015 — emitting the Undo is not a case of the CASE_MANAGER's withdrawal commit
TRIG-11-007 MUST The offer-case-ownership-transfer trigger (TRIG-11-001) MUST accept an optional end_time in its request body and, when given, set it as the end_time of the proposal's inner Offer, which the CASE_MANAGER carries to the Offer it makes as the deadline to answer (CM-21-016). Without it the Offer carries no end_time.

The owner is the party that knows how long it can wait for an answer, so the deadline is set where the transfer is proposed.
Extends: TRIG-11-001
Uses definition from: CM-21-016

Trigger API Contract Stability and Dispatch Registry

ID Priority Requirement Related
TRIG-12-001 MUST Every trigger endpoint (/trigger/ and /demo/) MUST declare a response_model naming the TriggerResult subtype its verb returns, so the OpenAPI document describes the real response body of each verb.

Without a declared response_model, OpenAPI documents no response body. Then clients and reviewers cannot see the different body shapes that the verbs return.
TRIG-12-002 MUST A test parametrized over the trigger registry (TRIG-12-004) MUST pin the response body of every trigger verb to an exact key set.

activity is null whenever the BT captured nothing; excluding None would silently drop a key clients receive today. Pinning the exact set, rather than asserting one key is present, is what turns a body change into a failing test.
Uses definition from: TRIG-12-004
TRIG-12-004 MUST A single verb-keyed trigger registry MUST be the sole source that maps each trigger verb to its request model, use-case class, result type and exposure. The exposure is general-purpose or demo-only.

The registry is for enumeration, not for routing, because a route already knows its verb. With enumeration, tests can assert TRIG-08-003/004, TRIG-12-001, and TRIG-12-002, so inspection is not necessary. Enumeration also finds a use case that no route reaches. When the registry holds no behavior, it cannot become a second layer of code for each verb (ADR-0110).
TRIG-12-005 MUST Trigger response_model serialization MUST keep FastAPI's defaults for response_model_exclude_none, _exclude_unset, _exclude_defaults and _by_alias, so that a key whose value is null is still emitted.

activity is null whenever the BT captured nothing. If serialization excluded None, it would drop a key that clients receive today, and no client would be told.
TRIG-12-007 MUST Every trigger route MUST correspond to exactly one registry row, and every row to exactly one route.

A route with no row escapes every test that enumerates the registry. A row with no route names a verb that no caller can reach (ADR-0110).
Extends: TRIG-12-004
TRIG-12-008 MUST Every Svc*UseCase class under vultron/core/use_cases/triggers/ MUST appear in exactly one registry row.

A trigger use case with no row is code that no route reaches. The registry is for enumeration, so a test can find such a use case only through its row (ADR-0110).
Extends: TRIG-12-004
TRIG-12-009 MUST NOT The trigger registry MUST NOT contain per-verb behavior. It holds data and a lookup only.

A route already knows its verb, so the registry does not route. Behavior in the registry would make it a second layer of code for each verb (ADR-0110).
Extends: TRIG-12-004

Leaving a Case

ID Priority Requirement Related
TRIG-13-001 MUST The system MUST expose a general-purpose leave-case trigger at POST /actors/{actor_id}/trigger/leave-case that accepts a case_id and sends Leave(VulnerabilityCase) from the requesting actor, addressed to the case's CASE_MANAGER. It accepts a call from any participant of the case; what the Leave means for the case is decided by the CASE_MANAGER on receipt (CM-23-002, CM-23-003).

A participant that joined a case closes its part in the case when it leaves the case (CM-23-001). It never uses Reject(Offer(VulnerabilityReport)), which a case refuses from all senders (CM-23-019, ADR-0144). A production deployment needs a trigger for this step, because production mode does not mount demo verbs (TRIG-09-002). The verb has the name of the message, not 'close'. When a participant that is not the owner leaves, the case stays open (ADR-0145).
Refines: TRIG-02-004
See also: CM-23-002 — context for the reader
See also: CM-23-003 — context for the reader
TRIG-13-002 MUST The leave-case trigger MUST run the pre-close Actuator call-out (PreCloseAction) for every caller before it sends the Leave.

The pre-close step is the leaving actor's own integration work, such as closing its ticket, so it runs where that actor decides to leave. Running it when the actor's replica applies its closure entry would put local policy into replica application, which CM-23-016 forbids (ADR-0145).
Extends: TRIG-13-001
TRIG-13-003 MUST When the actor calling leave-case is the Case Owner and its replica records an active embargo (EM.ACTIVE or EM.REVISE), the trigger MUST fail before the pre-close call-out runs and before anything is sent, with an error that says to terminate the embargo first.

The CASE_MANAGER refuses the Case Owner's Leave while an embargo is active (CM-23-011). Checking first keeps the owner's own systems from acting on a close that would be refused (ADR-0145).
Supersedes: TRIG-13-002
TRIG-13-004 MUST When the pre-close call-out (TRIG-13-002) fails, the leave-case trigger MUST fail with nothing sent.

A Leave sent after a failed pre-close step would close the actor's part in the case while its own integration work stayed undone. Failing first lets the actor fix that work and leave again.
Extends: TRIG-13-002

Use-Case Organization

Requirements for the physical package layout of the use_cases package, registry synchronization, test mirroring, and documentation of the trigger-to-received-to-sync information flow pattern.

File ID: UCORG

Package Layout

ID Priority Requirement Related
UCORG-01-001 MUST Use-case classes that process inbound received messages MUST reside under vultron/core/use_cases/received/

Received use cases answer messages that arrive from other actors. Trigger use cases start an action for the local actor. The two kinds have different callers and result types (UCORG-05-002, UCORG-05-007). When each kind has its own package, the location of a class tells a reader which kind it is, and the reader finds the use case for each received message in one place.
UCORG-01-002 MUST Trigger use-case classes that implement actor-initiated behaviors MUST reside under vultron/core/use_cases/triggers/

Trigger use cases start an action for the local actor through the trigger driving port. Received use cases answer messages from other actors. The two kinds have different callers and result types (UCORG-05-002, UCORG-05-007). When each kind has its own package, the location of a class tells a reader which kind it is.
UCORG-01-003 MUST NOT The vultron/core/use_cases/ package root MUST NOT hold anything but __init__.py, README.md, the query/, received/ and triggers/ subpackages, and shared private helper modules.

A use case at the package root does not show which kind it is, for example a received use case or a trigger use case (UCORG-01-001, UCORG-01-002). The root is for code that the use cases share and for the package's README.md, which UCORG-04-001 requires. The use-case registry is in vultron/semantic_registry/, not in this package, and the dispatcher receives the map by injection.
UCORG-01-004 MUST Query use-case classes, which compute a read-only result from the DataLayer and change no state, MUST reside under vultron/core/use_cases/query/.

A query use case answers a question about the local actor's state, such as which CVD actions an actor may take in a case. It is neither a received use case nor a trigger use case, and its result type differs from both (UCORG-05-002, UCORG-05-007). A package of its own tells a reader that the class changes nothing.

Registry Synchronization

ID Priority Requirement Related
UCORG-02-001 MUST Any relocation or rename of a use-case class MUST update its SEMANTIC_REGISTRY entry in vultron/semantic_registry/ in the same commit. The registry is the single source of the MessageSemantics → use-case-class mapping, projected by use_case_map() in vultron/semantic_registry/__init__.py

The dispatcher finds each use case only through the map that use_case_map() builds from SEMANTIC_REGISTRY. If a class moves or gets a new name and its entry does not change, the import fails or a message routes to no use case. A change in one commit keeps every commit in a state where routing works.
UCORG-02-002 MUST A dispatch coverage test MUST verify that every MessageSemantics value registered in SEMANTIC_REGISTRY resolves to a callable class and that dispatch succeeds for a representative event

A registry entry that names a missing or wrong class fails only when its message arrives. A test over every registered value finds such an entry before a message reaches it. A dispatch of a representative event also shows that the dispatcher can call the class that it finds.

Test Layout

ID Priority Requirement Related
UCORG-03-001 MUST Use-case test modules MUST mirror the structural layout of the use-case source modules they test.

When the tests mirror the source layout, a reader finds the tests for a use case from its path.
Refines: TB-04-001 — testability.md
UCORG-03-002 MUST Each use-case subpackage MUST have a test subpackage at the same relative path under the test root.

When each subpackage has its test subpackage, a use-case package with no tests is easy to see.
Refines: UCORG-03-001

Information Flow Documentation

ID Priority Requirement Related
UCORG-04-001 SHOULD The trigger → received → sync information flow pattern SHOULD be documented in notes/ and summarized in a README.md under vultron/core/use_cases/

A trigger, the received message that it causes and the sync of the result are in different modules of triggers/ and received/, and no single module shows the whole flow. A note in notes/ gives the design. A README in the package lets a reader who opens the code find that note.

Use-Case Result Protocol

ID Priority Requirement Related
UCORG-05-001 MUST Every use-case execute() method MUST declare a return type that is UseCaseResult or a subtype (HandlerResult, TriggerResult); bare None or dict return types are not permitted

Makes the use-case contract explicit and machine-checkable. See ADR-0040 (docs/adr/0040-use-case-result-envelope.md).
UCORG-05-002 MUST Handler (received-side) use cases MUST return HandlerResult.

HandlerResult carries the verdict of the handler to InboxOutcome (IO-01-006). If a handler returns no result, the inbox cannot tell an applied message from a no-op, and it reports both as processed. A separate subtype also lets callers tell a received-side result from a trigger-side result without an isinstance check on the base. See ADR-0095.
UCORG-05-003 MUST The UseCase Protocol in vultron/core/ports/use_case.py MUST declare execute() -> UseCaseResult, not a return type of Any or None.

The UseCase Protocol is the contract that every use case implements. A return type of Any or None lets a use case return nothing or an untyped value, and type checkers cannot report it. A UseCaseResult return type keeps every result typed. No production call site is typed against the Protocol, so UCORG-05-004 checks each class.
UCORG-05-004 MUST An architecture ratchet test MUST verify that all concrete use-case classes in vultron/core/use_cases/ declare an execute() return annotation that is UseCaseResult or a registered subtype

The enforcement for UCORG-05-003. No call site is typed against the UseCase Protocol (the dispatcher routing table holds bare type values), so mypy alone does not report a non-conforming execute(); the ratchet catches it at CI time.
UCORG-05-005 MUST The ActivityResult subtype of TriggerResult MUST carry activity and emitting_actor_id. TriggerResult is the fieldless base of the trigger-side result hierarchy.

Several trigger verbs return response bodies with no emitting_actor_id or no activity. A base that required both fields could not describe those bodies without a change to live responses. Thus only ActivityResult carries both keys. See ADR-0110.
UCORG-05-015 MUST Each TriggerResult subtype other than ActivityResult MUST declare exactly the keys its verb's response body carries.

When each subtype declares exactly the keys of its verb, the type is the contract of the response body, and a router needs no per-verb shaping. See ADR-0110.
Uses definition from: UCORG-05-005
UCORG-05-016 MUST The TriggerResult base MUST reject unknown keys. A use case that grows a return key then fails loudly, and the key is not silently dropped from the body.

An unknown key that the base drops would disappear from the response body with no notice. A loud failure makes the author declare the new key on the subtype.
Extends: UCORG-05-005
UCORG-05-017 MUST HandlerResult MUST carry a disposition field of type HandlerDisposition and an optional reason.

The disposition is the verdict that DispatchNode maps onto the inbox outcome (IO-01-006). The reason says why a handler refused, deferred or skipped.
UCORG-05-018 MAY A TriggerResult subtype or a HandlerResult MAY carry further domain-specific result fields.

Some verbs return more than an activity, and a typed field states what that is. The type checkers then see each extra value a caller reads.
UCORG-05-019 MUST NOT A TriggerResult subtype or a HandlerResult MUST NOT carry a raw dict payload. The one permitted dict value is an emitted activity's JSON object (activity, offer, note), typed dict[NonEmptyString, Any].

A raw dict hides its keys from the type checkers. An emitted activity's JSON is the exception: its keys are JSON member names (CS-08-001), and core captures it from the BT blackboard as JSON and cannot type it without a wire import (UCORG-05-014).
UCORG-05-006 MUST NOT The trigger driving port MUST NOT declare dict or dict[str, Any] as a return type. It exposes one method, trigger(request, dl), whose return type is the TriggerResult subtype bound to the request's type, so a router receives the verb's typed result without a per-verb port method.

Propagating dict past the port defeats the typed contract at the router boundary. A per-verb method surface grows linearly with the verbs behind it, flattens each validated request into loose scalars that the next layer reassembles, and hides nothing (ADR-0110).
UCORG-05-007 MUST Trigger use cases MUST return TriggerResult.

A dedicated TriggerResult subtype makes trigger-side results structurally distinct from handler-side results without runtime isinstance checks.
Refines: UCORG-05-001
UCORG-05-008 MUST Both HandlerResult and TriggerResult MUST inherit from UseCaseResult.

Inheriting from the common base type ensures that all use-case return values satisfy the UseCaseResult Protocol contract.
UCORG-05-009 MUST HandlerDisposition MUST be a StrEnum whose members are exactly APPLIED, SKIPPED, DEFERRED, and REFUSED

A closed StrEnum follows the project idiom for fixed value sets (CVDRole, VultronObjectType) rather than an inline Literal. DEFERRED is a member because handler-side deferral is real: BufferOutOfOrderEntryNode and BufferPreGenesisEntryNode return SUCCESS after holding the received Add(CaseLedgerEntry) for replay once its predecessor arrives, which is neither a state change nor a benign no-op nor a refusal. DeferCheckNode decides the other kind of deferral — missing case context — before dispatch; the two are distinct and both map to InboxOutcome.status == "deferred". See ADR-0095.
UCORG-05-010 MUST Every link between a received-side execute() and DispatchNode MUST declare and pass on the HandlerResult that execute() returns, not None. The links are DispatcherBase._handle(), DispatcherBase.dispatch(), the ActivityDispatcher Protocol, the adapter-level dispatch() helper, FastAPIDispatchAdapter.dispatch() and the DispatchAdapter Protocol.

The dispatcher chain is the only route from a handler to InboxOutcome. If one link declares None, it discards the verdict, and a handler that took no action is still reported as processed. _handle() is named because it is the link that calls execute(), and dispatch() only logs and delegates to it. An implementer who reads only the public method names can leave the first link at None and lose the verdict before any other link sees it. See ADR-0095.
UCORG-05-012 MUST When a dispatch finds no use case for the event's semantic type, the dispatcher MUST return an explicit REFUSED "no use case found" verdict (SE-05-002). It does not raise or return as though a handler ran, so the lookup failure never yields InboxOutcome.status == "processed".

No handler ran, so the outcome cannot be processed. The dispatcher returns a verdict, not an outcome, because HP-01-004 gives the InboxOutcome vocabulary only to DispatchNode. The dispatcher does not raise. A receiver that does not handle a message has not found it invalid (ADR-0140). A raise would answer the sender with a ProcessingFault. An activity that names no case does not take this path: routing uses the semantics only, and the handler refuses that activity (HP-05-002).
Extends: IO-01-006
Uses definition from: SE-05-002
UCORG-05-013 MUST A REFUSED disposition reaching InboxOutcome MUST be logged above DEBUG by the component that observes the completed outcome

run_inbox_pipeline logs every outcome.status at DEBUG. A refusal that only this line records would be invisible in normal operation, even when the dispatcher chain carries the verdict correctly (UCORG-05-010, IO-01-006). An operator must be able to see in the actor log that the actor refused a message.
UCORG-05-014 MUST A WireActivityResult model MUST exist in vultron/demo/ with a non-optional activity field typed as_TransitiveActivity.

Core captures activity as dict[str, Any] from the BT blackboard; a wire type there would violate ARCH-01-001. The demo-layer view types the raw dict as as_TransitiveActivity at the HTTP boundary, so ActorSession is fully typed without polluting core.
UCORG-05-020 MUST The demo layer MUST build each WireActivityResult by validating the activity key of the raw dict that post_to_trigger returns. A WireActivityResult is a typed view of the HTTP response body, not a use-case return value.

Validation at the HTTP boundary turns the response body into a typed wire object once. Every ActorSession method then reads a typed activity, and a malformed body fails where it arrives.
Extends: UCORG-05-014
UCORG-05-021 MUST NOT WireActivityResult MUST NOT be placed in vultron/core/. as_TransitiveActivity is a wire-only class with no core counterpart, and core does not import wire (ARCH-01-001).

ARCH-25-003 aliases the paired domain types onto core, not the activity envelopes. A core model typed as_TransitiveActivity would thus need a wire import, which ARCH-01-001 forbids.
Derives from: ARCH-01-001
UCORG-05-022 MUST NOT A demo-layer typed view MUST NOT reuse the class name of a core result class. The plain ActivityResult name belongs to the core TriggerResult subtype (UCORG-05-005), whose activity is the JSON object captured from the BT blackboard.

Two ActivityResult classes in different layers, one JSON and one wire, would look the same in a traceback. The wire-typed one thus takes the Wire prefix that WireCaseLedgerEntry already uses (ARCH-04-005).
Uses definition from: UCORG-05-005

VINCE Data Handling in the Case Shadow Tool

Rules for data read from a VINCE instance by the case shadow tool's VINCE case reader: what logs may carry, how the API credential is read, and the only ways it may enter the repository or a publication. Readers and retention add no requirement: each VINCE user runs the shadow with their own credential, and nothing is left on the host after the tool's process exits (SHD-01-003).

File ID: VSD

Runtime Handling

ID Priority Requirement Related
VSD-01-003 MUST NOT A shadow log record MUST NOT carry VINCE case content, such as a title, description, post, vul detail or contact detail.

Logs are copied into issues, CI artifacts and Coding Agent sessions, so a log record is a publication path. VINCE case, activity and actor ids may still be logged, which keeps records joinable without carrying what the embargo protects.
VSD-01-004 MUST The VINCE API credential MUST be read only at runtime, from the environment.

The credential is a secret, so it is kept outside the code, the repository and every configuration file. Configuration files live in the repository, and a credential read only from the runtime environment has no path into a commit.
VSD-01-005 MUST NOT The VINCE API credential MUST NOT appear in a log record, exception message or object repr.

Logs and errors are copied out of the host. A credential that is never rendered cannot leak through them.

Repository and Publication

ID Priority Requirement Related
VSD-02-006 MUST NOT The sanitizer's output MUST NOT contain a string value of its source case other than an enumerated VINCE API value.

Sanitizer output is committed without clearance, so a single string that survives from the source would publish it.
VSD-02-007 MUST The sanitizer MUST refuse a VINCE response field it does not classify, with an error naming the field.

A new API field the sanitizer has not classified could carry case content straight through. Refusing it fails closed.
VSD-02-008 MUST NOT The sanitizer's output MUST NOT contain an id of its source case, whether the id is a string or a number.

A VINCE case, participant or post id identifies the real case as surely as its text does, and VSD-02-006 covers only string values. Sanitized output keeps none of the source's ids, so each id is replaced by a synthetic one, consistent across the case.

Vocabulary Model

Requirements governing how ActivityStreams 2.0 vocabulary types are defined, registered, configured, and deserialized in the Vultron wire layer. The vocabulary model is the foundation of the inbound pipeline: every activity must be deserialized into a known vocabulary type before semantic extraction can assign it a domain meaning.

File ID: VM

Vocabulary Registration

ID Priority Requirement Related
VM-01-001 MUST Every concrete wire-layer AS2 class (object, activity, or link) MUST be registered in the shared VOCABULARY registry automatically at class-definition time

The parser can resolve a type value only to a class that a registry holds. A class that a developer must register by hand is unknown to the parser when that step is forgotten, and an inbound activity of that type is refused. Registration when the class is defined removes that manual step, so a new class cannot be defined and still be missing from the registry.
VM-01-003 MUST New vocabulary types MUST be importable at startup without explicit registration calls in application code

Registration happens when a module is imported (VM-01-005). A vocabulary module that no code path imports registers nothing, and the parser then refuses its types. Importing vultron.wire.as2.vocab.objects or vultron.wire.as2.vocab.activities imports every module in that package, so the set of known types does not depend on which single modules the application imported first.
VM-01-004 MUST The VOCABULARY registry MUST map each wire class from a key that is its full wire class name, such as as_VultronPerson.

The two registries answer different questions, so they carry different key forms: VOCABULARY answers "which class is named this?", WIRE_TYPE_MAP answers "which class does this wire type value deserialize to?" (VM-01-008). The as_ prefix is never part of an AS2 type value, so nothing external depends on this key form (ARCH-23-003).
VM-01-016 MUST NOT This codebase MUST NOT read a VOCABULARY key as an AS2 type value.

A VOCABULARY key is a Python class name, which no peer emits as a type. A lookup that accepts one lets an inbound "type": "as_Activity" resolve to a class, so a message no AS2 sender could write is parsed. A class's type_ annotation does not refuse it for every class: as_Activity.type_ is a bare str.
Derives from: VM-01-004
VM-01-009 MUST VOCABULARY keys MUST be disjoint from core vocabulary keys (ARCH-23-002).

The class-name form is what keeps these keys disjoint from CORE_VOCABULARY, so no wire class shadows a core type.
Refines: ARCH-23-002
VM-01-005 MUST Vocabulary type registration MUST happen automatically at package import time, with no explicit per-type registration call at any call site.

A registration call that each call site must make is a step that a call site can omit. When it is omitted, the type is unknown only on that path, and the defect shows only for the activities that take it. Registration as an import side effect makes the registry the same for every caller.
Refines: VM-01-001
VM-01-006 MUST A VocabNamespace enum (values: AS, VULTRON) MUST be defined in vultron/wire/as2/vocab/base/enums.py and used to annotate the provenance of each vocabulary class

The namespace tag tells which vocabulary a class belongs to: ActivityStreams or Vultron. The generator of the JSON-LD context document reads the tag to choose the classes it lists. One enum in one module gives its readers one value to compare, instead of a string that each reader can spell differently.
VM-01-007 MUST This codebase MUST check registration completeness against the wire type that a class presents, not against the module it lives in. A class's presented type is its type_ field default, or its class name without any as_ prefix when that default is None.

A registration check that looks at modules can skip a module for the same reason that the module failed to register. A module with no own type_ annotation looks like a module of aliases or abstract classes, and that missing annotation is the defect the check looks for. A check on the type value that each class presents does not depend on how a module is written, so it finds a class that presents a distinct wire type but registered nothing.
Verifies: VM-01-001
VM-01-010 MUST A test MUST assert that each as_Base subclass whose presented type equals its own class-name-derived value is reachable in a wire registry under that value.

A class that presents a distinct wire type but registered nothing cannot be reached by an inbound payload that carries the value it emits.
Implements: VM-01-007
VM-01-011 MUST The test of VM-01-010 MUST hold its exceptions in a declared exemption set that names, for each member, the requirement or reason that exempts it.

Each exemption names its reason, so a reviewer can see why a class is exempt. Abstract roots such as as_Object and as_VultronObject present their own name and are unregistered by design, so they are members of the exemption set.
Extends: VM-01-010
VM-01-008 MUST The WIRE_TYPE_MAP registry MUST key each class by the wire type value that it emits. That value is its declared type_ default or, absent one, its class name without the as_ prefix, as VM-03-001 assigns at construction.

A key that is no object's type value cannot be reached from the wire. A key derived from the emitted value is the value an inbound payload carries.
Uses definition from: VM-03-001 — The class-name fallback must match the value set_type_from_class_name assigns.
VM-01-012 MUST NOT This codebase MUST NOT register a class in WIRE_TYPE_MAP under its class name when that name is not the type value it emits.

A class-name key lets a caller with a class name resolve a wire class by a coincidence of names, which ARCH-23-002 forbids: a class-name key such as VultronPerson is also the name of a core type.
Extends: VM-01-008
VM-01-013 MUST Exactly one class MUST own a given type value in WIRE_TYPE_MAP. The sole exception is a sanctioned shadow, which the verifying ratchet enumerates.

One owner for each type value gives the inbound lookup one answer for each value.
Extends: VM-01-008
VM-01-017 MUST NOT A typed reference MUST NOT hold a WIRE_TYPE_MAP or VOCABULARY key. It carries the type of the object it names, and the parser tells it from a whole object of that type by its shape (MV-10-011), not by a registry lookup.

A typed reference shares its type with the class that owns that value, a case reference with the case. A key of its own would take the value from its owner or add a type no sender emits, and either breaks the one owner for each value that VM-01-013 requires.
Refines: VM-01-013
Uses definition from: MV-10-011

Base Model Configuration

ID Priority Requirement Related
VM-02-001 MUST Every wire-layer AS2 Pydantic model MUST inherit from as_Base a model_config that sets a camelCase alias generator, validate_by_name and validate_by_alias, and no strict mode.

One inherited configuration makes every wire class read and write field names in the same forms: camelCase names on the wire (VM-07-002) and Python names in code. A class with its own configuration can send snake_case keys or refuse a field given by its Python name, and only the activities that use that class show the defect. Strict mode stays off because it would refuse lenient inbound data that the wire branch exists to accept, such as an ISO string for a datetime field.
Refines: CS-14-001
VM-02-002 MUST The @context field (as_context) MUST use explicit validation_alias="@context" and serialization_alias="@context" because @ is not a valid Python identifier character and cannot be handled by the camelCase alias generator

@ cannot occur in a Python identifier, and the camelCase alias generator cannot produce @context from a field name. Without the explicit aliases, the field is sent as context_, and a receiver does not find the JSON-LD context that VM-10-001 requires a message to declare.
Extends: VM-02-001
VM-02-003 MUST Wire-layer models MUST provide to_json(), to_dict(), and from_json() convenience methods that exclude None values and serialize using aliases by default

When each caller chooses its own serialization options, the same object can give different JSON on different code paths, for example with null fields on one path and none on the other. Shared methods with the project defaults give one output for one object, and they keep these output rules in one place.

Type Auto-Inference

ID Priority Requirement Related
VM-03-001 MUST The as_type field on every concrete wire-layer class MUST be set automatically at construction time if not supplied by the caller

A receiver selects the class for an inbound object by its type value, and the parser refuses an activity with no recognizable type (MV-01-001). If a sender had to set type by hand, an object built without it would be sent with no type, and the receiver would refuse it. Setting it at construction means that every object that this implementation sends carries a type.
VM-03-002 MUST A wire-layer class that presents its own class-name-derived AS2 type value MUST narrow type_ to a Literal[...] of that value. A class that VM-01-011's exemption set names is exempt.

Auto-registration treats an own type_ annotation as the sign that a class is concrete, and it keys the entry on the class name (VM-01-004). VM-03-001 fills type_ from the class name when a class inherits no default. So a class with neither an annotation nor an inherited default presents a distinct wire type but registers nothing, and the parser cannot resolve that type to a wire class. The annotation is then the one declaration of a distinct wire type, which VM-01-007 checks.
Extends: VM-03-001
Implements: VM-01-001
Uses definition from: VM-01-011
VM-03-004 MUST NOT A semantic alias that must not be listed in VOCABULARY under its own class name MUST NOT declare its own type_ annotation.

Any own type_ declaration lists the class in VOCABULARY under its class name. The prohibition covers only aliases that must not be listed there. A listing is not a lookup: no wire type value resolves through VOCABULARY (VM-01-016).
VM-03-003 MUST NOT as_type values MUST NOT start with "as_" in serialized wire output

The as_ prefix marks a Python wire class name (ARCH-14-001). It is not part of any ActivityStreams or Vultron type value. Another implementation that gets as_Note finds no such type in either vocabulary and cannot read the object. The registry also keys WIRE_TYPE_MAP by the value without the prefix (VM-01-008).
Constrains: VM-03-001

ID Generation

ID Priority Requirement Related
VM-04-001 MUST All wire-layer objects MUST have a globally unique as_id field set at construction time by generate_new_id() if not supplied

Other objects refer to an object by its id, the DataLayer stores it under that id, and receivers use it to detect a repeated delivery. An object without an id cannot be referenced, stored or checked for a repeat. A value set at construction means that no object exists without one. A random UUID in a urn:uuid: URI gives an ID in full URI form (OID-01-001) that needs no server configuration.
Implements: OID-01-001

Vocabulary Extension

ID Priority Requirement Related
VM-05-001 MUST A new Vultron-specific domain type MUST be defined in vultron/core/models/. It inherits from CoreObject if it has an AS2 shape, or from CoreRecord if it is a non-AS2 bookkeeping record.

ADR-0099 makes AS2 a serialization of the core model rather than a parallel hierarchy, so a domain type defined as a wire class would reintroduce the second hierarchy that decision removed.
VM-05-003 MUST A new Vultron-specific domain type MUST define type_ as a Literal[str] field that matches its wire type name.

The Literal field is what makes registration through __init_subclass__ fire automatically: in CORE_VOCABULARY for a CoreObject, and in CORE_TYPE_MAP for a CoreRecord-only type.
Extends: VM-05-001
VM-05-004 MUST A wire-facing as_ name for a new Vultron-specific domain type MUST be an alias of the core class (ARCH-25-003), not a separate class.

A separate wire class for a domain type would reintroduce the second hierarchy that ADR-0099 removed. See ARCH-14-001 for the as_ naming rule.
Extends: VM-05-001
Refines: ARCH-25-003
VM-05-005 MUST This codebase MUST write a separate as_ wire class only for unpaired AS2 vocabulary with no core counterpart. Such a class inherits from an AS2 base, such as as_Object or as_Activity. It sits in the vocabulary subpackage for its category, such as vocab/objects/ or vocab/activities/, where that subpackage's __init__.py discovers it.

Unpaired AS2 vocabulary has no core class to alias, so it is the one place a wire class of its own is needed.
VM-05-002 MUST Adding a new vocabulary type that represents a domain concept MUST be accompanied by: (a) a corresponding domain-layer Pydantic model in vultron/core/, (b) a handler use case in vultron/core/use_cases/, and (c) at least one round-trip serialization test.

A vocabulary type with no use case gives the receiver nothing to act on. With no pattern, the activity is classified UNKNOWN and refused. With a pattern but no use case, the dispatcher reports "no use case found" and refuses it (SE-05-002). A round-trip test detects a field whose wire name or type does not survive serialization and parsing.

Rehydration

ID Priority Requirement Related
VM-06-001 MUST Before any wire-layer activity is passed to semantic extraction, callers MUST attempt to rehydrate all nested URI string references into fully typed objects via rehydrate(obj, dl)

Semantic extraction matches an activity on the types of its nested objects. A nested object that is still a bare URI does not satisfy a type constraint (SE-01-006), so an activity whose objects the receiver already holds would not match its pattern. Rehydration first replaces the references that the DataLayer can resolve with the stored objects, so the pattern sees their real types.
Implements: SE-01-002 — semantic-extraction.md
VM-06-002 MUST rehydrate() MUST receive the active DataLayer instance via the dl parameter

Each actor has its own store (DL-07-002, DL-07-003), so a reference resolves only in the store of the actor that received the activity. A dl parameter makes the caller name that store. A global or default store could resolve the reference against the wrong actor's data, or against no data.
VM-06-003 MUST Rehydration MUST also rehydrate each URI string reference in a rehydrated object's nested fields, recursively, up to MAX_REHYDRATION_DEPTH levels.

A pattern can constrain an object inside an object, as in Accept(Invite(...)). If rehydration expanded only the top level, the inner reference would stay a bare URI and the pattern would not match. The depth limit stops unbounded recursion on a reference cycle or a very deep structure.
VM-06-004 MUST Rehydration MUST keep a URI it cannot resolve, carry on without raising, and log it: at WARNING in dl.hydrate(), at DEBUG in rehydrate(). This covers a reference in a slot that admits a URI, to an object the DataLayer does not hold. Of those slots, rehydrate() resolves only an activity's nested object.

An unresolved reference is normal: the object can be on another server or not yet received, and raising would refuse a valid activity. Keeping the URI lets a later step treat the object as unresolved (SE-01-006, VAM-01-009, AKM-05-007). In dl.hydrate() this actor stored the reference, so a missing object is a data gap an operator must see. In the inbound rehydrate() it is the ordinary cross-container case, and the inbox fetches the object next.
VM-06-005 MUST If a rehydrated object's as_type is not found in the vocabulary registry, rehydration MUST raise KeyError or ValueError rather than returning a partially constructed object

A partly built object carries a shape that no registered class defines, and pattern matching and use cases would then act on fields that are missing or wrong. Raising stops the activity at rehydration, where the unknown type is the reported fault, and no later step acts on a guess.
VM-06-007 MUST This rule covers an object-only slot: one whose declared type is an as_Object subclass that admits no str branch, such as as_CaseStatus or list[as_Activity]. For a bare IRI in such a slot, rehydrate() MUST resolve the IRI through the supplied DataLayer.

ARCH-25-009 requires an object slot to hold the whole object. A bare IRI in a slot that cannot hold a string must become the real object or be refused. rehydrate() already holds the DataLayer (VM-06-002), so it can read the real object and the real actor.
Refines: VM-06-001
Depends on: VM-06-002 — Materialisation needs the dl parameter that requirement mandates.
Refines: ARCH-25-029
VM-06-009 MUST When rehydrate() cannot resolve a bare IRI in an object-only slot (VM-06-007), it MUST refuse with a VultronReferenceResolutionError that names the field and the IRI. It refuses both when the IRI resolves to nothing and when it resolves to an object that is not an AS2 object.

A slot that cannot hold a string must hold the real object or the activity must be refused, so a failed resolution has no other outcome.
Uses definition from: VM-06-007
VM-06-010 MUST NOT rehydrate() MUST NOT fabricate a placeholder object for a bare IRI in an object-only slot (VM-06-007).

A placeholder is not the object the IRI names, so the activity would act on an object that does not exist.
Uses definition from: VM-06-007
VM-06-011 MUST NOT rehydrate() MUST NOT synthesize a value for any field that a placeholder for a bare IRI would have required.

A placeholder needs values for its required fields, such as an actor, and an invented actor attributes the activity to an actor that did not perform it.
Extends: VM-06-010
VM-06-012 MUST NOT rehydrate() MUST NOT substitute, in an object-only slot (VM-06-007), a shape that the slot cannot hold.

A substituted shape either fails validation later, away from its cause, or is read as an object of the wrong kind.
Uses definition from: VM-06-007
VM-06-008 MUST A wire-branch caller that resolves an AS2 type value MUST use a lookup that returns only classes the wire registry holds. Those are as_Base subclasses, and classes registered in WIRE_TYPE_MAP as their own wire form (ADR-0211).

A core-map hit for a wire-branch caller is a coincidence of names, not a wire counterpart (ARCH-23-002). Registry membership, not as_Base ancestry, is the test: the canonical VulnerabilityCase is a core class registered as its own wire form (ADR-0211).
Implements: MV-04-004
VM-06-013 MUST The core-type-map fallback (ARCH-12-010) MUST be reachable only by a caller that asks for it explicitly, never as the default answer to a wire-branch caller.

A permissive default gives that answer to every caller that does not filter it, and a filter in one caller does not protect the others. A wire-only default gives a new caller the safe answer with no extra code.
Uses definition from: ARCH-12-010 — ARCH-12-010's registration duty stands; what changes is which callers reach the map it fills.
VM-06-014 MUST A caller that may legitimately receive either branch MUST state that in its call, rather than inherit it from the lookup's default. Such a caller is a persistence read path that reconstructs whatever was stored.

A stated need is visible at the call site, so a reviewer can see which callers reach the core map and why.
Extends: VM-06-013

Serialization Rules

ID Priority Requirement Related
VM-07-001 MUST Serialized wire-layer objects MUST exclude None fields.

Under the rule "if present, then non-empty" (CS-08-001), a null value means the same as no value. A sender that emits null gives receivers a second form of one absence to handle, and a receiver that reads it as a value can act on it. Leaving the field out gives one form.
VM-07-005 MUST Serialized wire-layer objects MUST exclude empty string fields.

Under CS-08-001 a blank string means the same as no value, so a sender that emits "" gives receivers another form of one absence, and a receiver that reads it as a value can act on it.
Extends: VM-07-001
VM-07-003 MUST NOT object_to_record() MUST NOT be called on an object whose as_type starts with "as_"

object_to_record() stores an object in the table that its type value names, and a later read finds the class by that value. An as_ value is a Python class name, not a wire type value (VM-03-003). A record stored under it would be in a different table from the other objects of its type, so a read or a query by the real type value would not find it.
VM-07-004 MUST serialize_as_any=True MUST be declared on any Pydantic model field that holds an object whose concrete runtime type is a subtype of the field's declared type, at both the persistence serialization boundary and the wire delivery serialization boundary. Omitting serialize_as_any=True at either boundary causes the serializer to use the declared (base) type's schema, silently dropping all subtype-specific fields.

By default, Pydantic v2 serializes a field by its declared type. A field typed as as_Object that holds an as_CasePreview is serialized with the as_Object schema, so the stub's own fields (summary, activeEmbargo, caseStatus) are dropped with no error. Both the persistence boundary and the delivery boundary need the flag: a correct stored copy still gives wrong wire output if the delivery serializer drops the fields.

Static Object Integrity

ID Priority Requirement Related
VM-08-001 SHOULD Objects intended to be static once created (e.g., vocabulary registry entries, canonical example objects) SHOULD use immutable (frozen) configuration so that any attempt to modify them at runtime raises an exception

Registry entries and canonical example objects are shared by every caller that reads them. If one caller changes such an object in place, every later caller sees the change, and the defect shows far from its cause. A frozen object raises at the change, where the cause is.
VM-08-002 MUST A received wire Activity MUST carry the JSON body that arrived as its received evidence, held apart from the parsed object graph. The evidence is that body as the parser decoded and re-serialized it, before anything expands, validates or hydrates it.

The received artifact is the evidence of what arrived, and the ledger replicates it via Add(CaseLedgerEntry). A class-level frozen=True cannot hold it: frozen does not reach nested models, and since ARCH-25-003 the nested objects are mutable core classes. The evidence is therefore a value taken at parse, not a property of the graph.
VM-08-005 MUST NOT A received wire Activity's evidence MUST NOT change when the parsed activity, any object nested in it, or the caller's body is mutated.

Evidence that changes with the parsed graph no longer records what arrived, so the ledger would replicate a body no sender delivered.
Extends: VM-08-002
VM-08-006 MUST When routing or use-case execution needs a more hydrated form of a received activity, this codebase MUST produce that form as a separate object.

Hydrating the parsed activity in place would change the object that the evidence was taken beside, so the hydrated form is a copy.
Extends: VM-08-002
VM-08-007 MUST A more hydrated form of a received activity MUST carry the received activity's evidence unchanged.

The routing copy is what the use case and the ledger see, so it must claim the same arrival as the activity it was built from.
Extends: VM-08-006
VM-08-008 MUST A replay of a deferred activity, or a load of an archived one, MUST be parsed again from the received body held for it. It carries that body as its evidence.

The deferred record and intake's record keep the sealed body (IO-03-009, CLP-10-017), so a replay carries the first delivery's evidence and a load sees the body that arrived (ADR-0149).
Refines: VM-08-002
VM-08-009 MUST A resend of an archived activity with the same body MUST be routed as the archived copy, parsed from the body intake archived. It carries that body, the first delivery's, as its evidence.

The archived copy routed for a resend is the first delivery's sealed body, so carrying it as evidence claims exactly the event that arrived first. The repeat guards then decide, so a committed act is a repeat and an act that never committed, such as a failed one, runs as a first delivery and records that body (ADR-0214). A resend of a different body under a held id is refused, not routed (IE-10-002), so an id's evidence has one answer.
Refines: VM-08-002
VM-08-010 MUST NOT An activity routed or rebuilt from anything other than a delivery's sealed body carries no received evidence. This codebase MUST NOT give it the evidence of a different delivery.

A resend is another delivery, so its own body never becomes the evidence of the copy routed in its place: that would claim the wrong event.
Extends: VM-08-002
VM-08-004 MUST The factory MUST produce an emitted wire Activity blob as a complete, frozen object before any port or adapter receives it.

VM-08-003 states what participants can observe: the ledger copy is identical to the delivered activity. This requirement and its siblings state how this codebase meets it. The factory alone makes the activity complete.
Implements: VM-08-003
VM-08-011 MUST This codebase MUST use the exact blob returned to core as both the delivery payload and CaseLedgerEntry.payloadSnapshot.

The delivery payload and the ledger copy are then one blob, so they cannot differ.
Implements: VM-08-003
VM-08-012 MUST NOT A port or adapter MUST NOT enrich, mutate or re-derive an emitted blob after it leaves the factory.

A change after the factory would make the delivered activity differ from the blob that core recorded.
Implements: VM-08-003

Vocabulary Namespace and JSON-LD Context

ID Priority Requirement Related
VM-10-002 MUST The wire root as_Base and the core root CoreObject MUST default @context to the VM-10-001 list, taken from the one constant DEFAULT_JSONLD_CONTEXT in vultron/core/models/base/context.py.

Both roots serialize objects onto the wire, and an activity and the objects it carries may come from either. One constant in core gives both layers the same value without a wire import in core (ARCH-01-001). A default on the root covers activities as well as Vultron objects, which a default on as_VultronObject alone did not (#5168).
Implements: VM-10-001
VM-10-005 MUST The AS2 (by_alias) serializer of as_Base and of CoreObject MUST omit the default @context from every object nested inside the document it dumps.

One rule on the two roots places the context for every object without call-site changes, so a new object type cannot start restating it. A nested object whose own @context is not the default, such as one parsed from a peer's message, keeps it, because dropping it could change how its terms expand.
Implements: VM-10-004
VM-10-006 MUST The project MUST publish one JSON Schema for each Vultron type term the context document declares. Each schema is published at ns/<wire version>/schema/types/<Type>.json, beside that context document, with that URL as its $id. It is generated from the Pydantic class that defines the term, in the form Vultron accepts. A typed reference (VM-01-017) contributes no schema, and a property term gets none.

An outside implementer needs a machine-readable description of each Vultron object, and a generated schema cannot drift from the model without a failing check. Object shapes share the wire version with the vocabulary (ADR-0106), so the schemas sit under the same version segment as the context. The schemas are informative: JSON Schema checks one layout while JSON-LD allows several, so the requirements, not the schemas, decide conformance (ADR-0181).
Uses definition from: VM-10-001
Uses definition from: VM-01-017
VM-10-007 MUST Every field that a Vultron object serializes onto the wire MUST have a JSON-LD term: either a context that a Vultron message or actor profile cites defines it at top level, or within a type-scoped context for a field of that type, or the field is declared a Vultron property and the context document maps it. The fields of nested models count, and a field excluded from serialization does not.

The AS2 context maps an unknown term to a blank node ("@vocab": "_:"), so a JSON-LD processor loses the meaning of a field with no term. An explicit declaration makes each new field's author decide whether AS2 already has the term (ADR-0194).
Uses definition from: VM-10-001
VM-10-008 MUST A Vultron property declaration MUST carry a one-line definition and its value kind.

The definition is what makes "one meaning per name" (VM-10-012) checkable, and the value kind is what the context document's typed term is written from (VM-10-010).
Refines: VM-10-007
VM-10-009 MUST NOT A Vultron property MUST NOT use a wire name that a context Vultron cites already defines at top level.

Vultron's context follows AS2's in @context, so a Vultron term with an AS2 name would silently replace the AS2 meaning for a JSON-LD reader. Where AS2 has the term, the field uses it (ADR-0194).
Refines: VM-10-007
VM-10-010 MUST The context document MUST type each Vultron property term by its value kind, as the AS2 context types its own: an IRI value as "@type": "@id", a received document kept verbatim as "@type": "@json", an array whose order matters with "@container": "@list", and a map keyed by IRIs with "@container": "@index".

Without a type a JSON-LD reader takes a link for plain text, expands the keys inside a verbatim document such as a ledger entry's payload snapshot, reads the keys of an IRI-keyed map as properties, and treats an ordered history as an unordered set. AS2 types its terms, so Vultron's terms are no weaker (ADR-0194).
Refines: VM-10-007
VM-10-011 MUST The term check of VM-10-007 MUST read the terms of each external context Vultron cites from a pinned, byte-for-byte local copy under third_party/jsonld/, whose pin record holds each source URL and SHA-256 digest.

A hand-written list of AS2 terms can disagree with the context a processor actually reads, and the field names declared in this codebase's own AS2 classes include Vultron additions. The copies follow the CSAF precedent (CSAF-05-002). The cited contexts are a W3C Recommendation and versioned contexts that do not change at their URLs, so no watch job follows them; a copy moves only when its pin is moved on purpose.
Implements: VM-10-007
VM-10-012 MUST Two Vultron property declarations that share a wire name MUST carry the same definition and the same value kind.

Each wire name has one global term, as in AS2, so one name cannot carry two meanings. A name used for two meanings is renamed apart instead (ADR-0194).
Refines: VM-10-008
VM-10-013 MUST A test MUST fail when a pinned external context copy (VM-10-011) differs from the digest its pin record holds.

The copies are never edited by hand (third_party/README.md), so a mismatch means the copy no longer is the context it claims to be, and the term check would judge fields against the wrong terms.
Refines: VM-10-011

Vultron Semantic–AS2 Mapping

Defines the authoritative mapping from each Vultron semantic message type (MessageSemantics enum value) to its ActivityStreams 2.0 wire representation. This is the single source of truth for how Vultron domain semantics are encoded as AS2 activity structures, isolating transport and wire-encoding concerns from the core domain logic and case-state machines.

File ID: VAM

General Mapping Conventions

ID Priority Requirement Related
VAM-01-001 MUST Every MessageSemantics enum value except the UNKNOWN and UNKNOWN_UNRESOLVABLE_OBJECT sentinels MUST have exactly one entry in SEMANTIC_REGISTRY carrying a non-None pattern that defines its AS2 wire representation

A semantic type with no pattern can never be extracted from a received activity. Its use case never runs, and every activity of that type is classified as unknown. One entry for each type gives the type one wire form, so two entries cannot disagree about it. The two sentinels name the results of a failed match, so they have no wire form.
VAM-01-002 MUST The AS2 activity patterns defined in this document MUST be implemented as ActivityPattern objects in vultron/wire/as2/extractor/_instances.py.

The registry modules import their patterns from one module. A reader can then see every wire form in one file, and no registry module builds its own copy of a form that can drift from the form this document defines.
VAM-01-002b MUST NOT AS2 activity pattern objects MUST NOT be defined in any module other than vultron/wire/as2/extractor/_instances.py.

A pattern built in another module is not in the file where a reader looks for the wire forms. It can also match a different shape from the pattern that _instances.py defines for the same form, and nothing compares the two.
Extends: VAM-01-002
VAM-01-003 MUST Pattern entries in SEMANTIC_REGISTRY MUST be ordered from most-specific to least-specific so that find_matching_semantics() returns the correct semantic for overlapping patterns

find_matching_semantics() returns the first pattern that matches. When a general pattern comes before a specific pattern that it also covers, the specific semantic type never matches, and the wrong use case runs with no error. _validate_registry_order() raises RegistryOrderError at import for each such order that it can detect.
VAM-01-004 MUST NOT Pattern matching MUST NOT rely on an unhydrated string field for type discrimination.

A URI string carries no type. A pattern that reads the type of an unhydrated field cannot tell, for example, an Offer of a report from an Offer of a case.
VAM-01-014 MUST Semantic extraction MUST rehydrate an AS2 activity before pattern matching, expanding each URI string reference to its full object through the DataLayer.

Rehydration gives each field its full object, so the type that the pattern reads is the type of the object.
Implements: VAM-01-004
VAM-01-005 MUST When a pattern specifies a nested activity as the object field, the outer activity's object MUST be a fully rehydrated AS2 activity object matching the inner ActivityPattern

Many semantic types differ only in the activity that they wrap, such as Accept(Invite(EmbargoEvent)) and Accept(Offer(VulnerabilityReport)). Only the type and fields of the inner activity tell them apart, so the inner activity must be a full object that the inner pattern can match.
VAM-01-006 MUST When a non-object_ field holds a URI string that cannot be rehydrated, pattern matching MUST treat the field as matching any expected type.

Peripheral reference fields (actor, target, context, etc.) do not drive semantic dispatch; conservatively matching them avoids false negatives when the DataLayer cannot expand every reference
VAM-01-009 MUST find_matching_semantics() MUST return MessageSemantics.UNKNOWN_UNRESOLVABLE_OBJECT when no pattern matches an activity of a registered verb whose object chain ends in a bare URI. The chain is the activity's object_, followed through each inline activity it holds, as rehydration left it.

UNKNOWN_UNRESOLVABLE_OBJECT is the specific signal for a known activity type whose object could not be resolved: it separates a data gap, which may resolve later, from an activity no pattern describes.
Supersedes: VAM-01-007
VAM-01-012 MUST NOT A scalar object_ constraint MUST NOT match a bare URI still unresolved after rehydration, and no ActivityPattern field may opt a pattern out of that rule.

SE-01-006 allows no exception: the position statement that once named its entry by id is a Read of the case's ledger (SYNC-17-001, ADR-0204). A pattern that could opt out would route an object of unknown type.
Implements: SE-01-006
VAM-01-013 MUST ActivityPattern.strict MUST govern only the target_ and origin_ constraints, leaving how the pattern matches object_ unchanged.

Once object_ is strict by default (SE-01-006), strict is the tool SE-08-004 names for a pattern whose target_ or origin_ is its sole discriminator. origin names where the object comes from as target names where it goes, so the two fields take a bare URI alike and tighten alike. Building a strict pattern with neither raises, since the flag would tighten nothing.
Implements: SE-08-004
VAM-01-007 MUST find_matching_semantics() MUST return MessageSemantics.UNKNOWN when no registered pattern matches the incoming activity, except where VAM-01-009 requires MessageSemantics.UNKNOWN_UNRESOLVABLE_OBJECT

A received activity needs one defined result even when no pattern describes it. UNKNOWN gives the inbox a value that it can refuse and log, in place of an exception or a guess at the nearest semantic type.
VAM-01-010 MUST This codebase MUST send a CaseStatus or a ParticipantStatus inline on the single Add that attaches it (VAM-08-002, VAM-08-004).

A status sent by reference would leave the receiver to fetch it before it could attach it. One Add with the status inline is the single message that brings it into the case (VAM-01-011, ADR-0137).
Refines: VAM-01-011 — this codebase's inline sending of the status records
Uses definition from: VAM-08-002
Uses definition from: VAM-08-004
VAM-01-015 MUST This codebase MUST send a Note inline on the single Add(Note) that attaches it (VAM-07-002).

Add(Note) is the one message that brings a note into a case (VAM-01-011), so the note travels on it. Create(Note) would be a second way to attach a note (ADR-0137).
Uses definition from: VAM-07-002
Refines: VAM-01-011
VAM-01-016 MUST This codebase MUST send a proposed EmbargoEvent inline on the Invite that proposes it (VAM-05-005).

The proposing Invite is the one message that brings a proposed embargo into a case (VAM-01-011). A received Invite can still name its terms by URI (ADR-0123).
Uses definition from: VAM-05-005
Refines: VAM-01-011
VAM-01-017 MUST This codebase's inbox MUST refuse a received Create(CaseStatus), Create(ParticipantStatus), Create(CaseParticipant) or Create(Note) as an unrecognized activity. It refuses a received Create of any Event other than an EmbargoEvent the same way.

VAM-01-011 leaves to the receiver how to handle a stray Create, and this item is the answer of this codebase. A Create stored with no ledger entry would change the case file outside the ledger (CLP-07-013).
Refines: VAM-01-019 — this codebase's refusal of the Create forms
VAM-01-018 MUST This codebase's inbox MUST report a received Add(CaseParticipant)[target=VulnerabilityCase] or Create(EmbargoEvent) as "no use case found" (SE-05-002, ADR-0140).

Each is the CASE_MANAGER's own record of a change (VAM-05-016, VAM-06-004), so the inbox recognizes it. Both are ledger records of the CASE_MANAGER that a replica copies from the ledger (ADR-0124), not messages a use case handles.
Uses definition from: SE-05-002

Embargo Management Messages

ID Priority Requirement Related
VAM-05-010 MUST This codebase MUST carry the proposed EmbargoEvent inline as the object of the Add(EmbargoEvent)[target=VulnerabilityCase] of VAM-05-008 and of the Reject(EmbargoEvent)[target=VulnerabilityCase] of VAM-05-009.

This is how this codebase meets VAM-05-008 and VAM-05-009, kept apart from them so that they state only what other participants observe (MS-12-010). This codebase matches the semantic type on the type of the object. An inline event lets the pattern read that type without depending on what the receiver's store holds. The vocabulary class types the object as as_EmbargoEvent with no reference form, so a reference that the receiver cannot resolve is refused (VM-06-009) and not deferred. That is a choice of this prototype reference implementation, not a protocol rule.
Implements: VAM-05-008
Implements: VAM-05-009
VAM-05-012 MUST This codebase MUST carry the EmbargoEvent in force inline as the object of the Leave(EmbargoEvent)[context=VulnerabilityCase] of VAM-05-011.

This is how this codebase meets VAM-05-011, kept apart from it so that it states only what other participants observe (MS-12-010). This codebase matches the semantic type on the type of the object. An inline event lets the pattern read that type without depending on what the receiver's store holds. The vocabulary class types the object as as_EmbargoEvent with no reference form, so a reference that the receiver cannot resolve is refused (VM-06-009) and not deferred. That is a choice of this prototype reference implementation, not a protocol rule.
Implements: VAM-05-011

Unrecognized Activities

ID Priority Requirement Related
VAM-09-002 MUST NOT MessageSemantics.UNKNOWN MUST NOT have a matchable pattern.

UNKNOWN needs a registry entry, because lookup_entry() resolves the event class and the use case for the fallback through it. If that entry had a pattern, UNKNOWN could come from a match as well as from no match, and a reader of the result could not tell which. The statement says "no matchable pattern" and not "no entry" for that reason.
VAM-09-003 MUST The SEMANTIC_REGISTRY entry for MessageSemantics.UNKNOWN MUST carry pattern=None.

A None pattern is how the registry keeps the UNKNOWN entry that lookup_entry() needs while giving the match loop nothing to select.
Implements: VAM-09-002