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 subclassesCallers 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 constructorFields 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 ... importOne 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
Error Handling
Internal Vocabulary Classes
Import Boundary Enforcement
TypeAlias Naming
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
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
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
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 stateWithout 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 sequenceAn 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 identifierAgents 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
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
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 frameworkKeeps 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
Semantic Extractor
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.
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
BT Library
State Management
Handler Integration
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
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
Actor Isolation
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 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 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/ 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 DetailsPreconditions - 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
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
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 caseThe 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 subtreeThe 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
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)
Testing
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
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
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
Import Organization
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
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
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 | 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
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
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
No Compatibility Shims
Method and Variable Naming Safety
Pydantic Models for Structured Data
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
Collection-Typed Pydantic Field Defaults
Extract Before Reuse
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
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
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
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
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
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.
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 || 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
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
Unit Testing
Integration Testing
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|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 argumentsA 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
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
Trigger Conditions
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 || 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 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
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 DetailsPreconditions - EM state is Active or Revise; reason Selector has succeeded - EM state: ACTIVE, REVISESteps 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 DetailsPreconditions - EM state is Active or Revise; reason Selector succeeded; EmbargoExitPolicyGuard returned FAILURE - EM state: ACTIVE, REVISESteps 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 DetailsPreconditions - 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 DetailsPreconditions - Flow A only; inbound EP received; actor declined to accept outright and the adjudication arm elects to counter - EM state: PROPOSEDSteps 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 DetailsSteps 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-policyA 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
Submodule Errors
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
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
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 typeThe 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 DispatchNodeKeeps 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 nameDispatcherBase._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 "..." | 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.
Response Headers
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.
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.
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.
FastAPI Response Serialization
AS2 Response Class Convention
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
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
Module Location
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
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
Ratchets as Predicates and State Groups
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
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
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 startupOther 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 endpointA 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 dependenciesA 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.mdA 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
Scenario Coverage
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 logicUsing 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 DetailsPreconditions - 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= 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 verbAnnounce 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 DetailsPreconditions - 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 referencesReceiving 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 DetailsPreconditions - 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 DetailsPreconditions - 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 DetailsPreconditions - 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 DetailsPreconditions - 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 DetailsPreconditions - 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 DetailsPreconditions - 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 DetailsPreconditions - 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 DetailsPreconditions - 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 DetailsPreconditions - 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 DetailsPreconditions - 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 DetailsPreconditions - 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 DetailsPreconditions - 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 DetailsPreconditions - 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 DetailsPreconditions - 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 DetailsPreconditions - 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 DetailsPreconditions - 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 DetailsPreconditions - 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 DetailsPreconditions - 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 DetailsPreconditions - 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 DetailsPreconditions - 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 DetailsPreconditions - 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] | 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 DetailsPreconditions - 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 DetailsSteps 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 DetailsSteps 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 | 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 | 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 DetailsPreconditions - 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 group8. [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 DetailsPreconditions - 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
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
Future: Registry and Query Tool
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
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
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
Outbox Delivery
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
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
Outbox Monitor Efficiency
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
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
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 completedAgents 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 changeAn 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
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.
Expiry and Reaping
How an expired ask is noticed, given that elapsed time is not an event.
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
Performance
Production Deferral
Case Prioritization
Backward Compatibility and Change Completeness
Performance Testing
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
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 DetailsPreconditions - 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
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 sentinelsMatching 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 specificfind_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 typeA 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 URIA 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
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
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 axisA 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 codeA 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 codebaseA 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
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
State Subsets and Guards
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 memberA 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
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 formatAn 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 availableOne 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 availableOne 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
Error Context
Authorization Logging
Data Access Logging
Performance Metrics
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
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
Testing
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
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
Containerization and Deployment
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
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
Test Coverage
Integration Test Coverage
Test Organization
Test Data Management
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
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
Strict Goal Markers
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
Maintenance
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 directlyA 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 handlersThe 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 parameterTrigger 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
Trigger Classification
| ID | Priority | Requirement | Related |
|---|---|---|---|
TRIG-08-001 |
MUST | The application MUST define a RunMode StrEnum with at least two values: PROTOTYPE and PRODThe 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 validationThe 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
Registry Synchronization
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
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 permittedMakes 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 subtypeThe 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 REFUSEDA 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 outcomerun_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
Repository and Publication
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 timeThe 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 classThe 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 defaultWhen 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 callerA 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 outputThe 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 suppliedOther 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 parameterEach 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 objectA 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 representationA 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 patternsfind_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 ActivityPatternMany 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_OBJECTA 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 |