Reference

Foundation Specifications

This page is normative

This page is considered a core part of the Vultron Protocol. This is a normative section of the documentation.

Rules Vultron inherits from the standards beneath it: ActivityStreams 2.0, ActivityPub, and HTTP. They cover addressing and delivery, HTTP status codes, and rules that only restate ActivityStreams, such as every object ID being an IRI. Each requirement carries a tag that names its standard: as2, activitypub, or http. Where Vultron requires one form among several that a standard allows, the rule is a Protocol requirement, not a foundation one. An implementer reads this page together with the Protocol page.

Behavioral Specifications

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

Actor Knowledge Model

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

File ID: AKM

Actor Addressing and Discovery

ID	Priority	Requirement	Related
AKM-05-001	MUST NOT	The absence of a local record of a peer actor MUST NOT prevent an actor from addressing an outbound activity to that peer. The peer's deliverable http(s) URI is sufficient for addressing; a fully resolved actor record is an enrichment (directory service), not a precondition for protocol participation.

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

Actor Discovery Profile

ID	Priority	Requirement	Related
AR-10-002	MUST	The profile endpoint MUST return HTTP 404 when the actor is not found HTTP defines 404 Not Found as the answer to a request for a resource the server does not have (HTTP-03-005). Vultron inherits the rule.

Code Style Specifications

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

File ID: CS

Datetime and Timezone Conventions

ID	Priority	Requirement	Related
CS-13-006	MUST	Wire-format datetime fields MUST serialize as RFC 3339 date-times with an explicit offset; a naive or offset-free value MUST NOT reach the wire. ActivityStreams 2.0 requires every date-time value to follow RFC 3339's date-time form, whose offset is mandatory. An explicit offset is what makes timestamps comparable as instants. Split from CS-13-005 (MS-12-010), which keeps Vultron's rules on which offset a timestamp carries.	Constrains: CS-13-005 — split from it (MS-12-010); CS-13-005 picks which offset, within this rule

HTTP Protocol Requirements

HTTP protocol requirements for the Vultron API, covering status codes, headers, and content negotiation.

File ID: HTTP

Content-Type Validation

ID	Priority	Requirement	Related
HTTP-01-002	MUST	Inbox endpoint MUST accept application/ld+json; profile="https://www.w3.org/ns/activitystreams" Content-Type This is the media type ActivityPub names for delivery to an inbox. Vultron inherits the rule rather than defining it.
HTTP-01-003	MUST	Inbox endpoint MUST reject requests with invalid Content-Type using HTTP 415 HTTP defines 415 Unsupported Media Type as the answer to a request whose content is in a format the target resource does not support.

HTTP Status Codes

The status codes HTTP itself defines for each outcome, which Vultron inherits (foundation, http). Where HTTP leaves the choice open, as with 422 for a schema failure, the code is this codebase's choice and the spec is project.

ID	Priority	Requirement	Related
HTTP-03-001	MUST	The API MUST return 200 OK for successful reads. Standard HTTP success code for GET and other read operations.
HTTP-03-003	MUST	The API MUST return 202 Accepted for queued processing. Indicates the request was accepted but processing is deferred to a background job.
HTTP-03-004	MUST	The API MUST return 400 Bad Request for malformed input. Signals that the client submitted a syntactically invalid request that cannot be parsed.
HTTP-03-005	MUST	The API MUST return 404 Not Found for missing resources. Indicates the requested resource does not exist in the system.
HTTP-03-006	MUST	The API MUST return 405 Method Not Allowed for unsupported methods. Informs the client that the HTTP method used is not supported on this endpoint.
HTTP-03-007	MUST	The API MUST return 413 Content Too Large for oversized payloads. Rejects requests exceeding the configured payload size limit (see HTTP-02-001).
HTTP-03-008	MUST	The API MUST return 415 Unsupported Media Type for invalid Content-Type. Rejects requests whose Content-Type header is not an accepted media type (see HTTP-01-003).
HTTP-03-010	MUST	The API MUST return 429 Too Many Requests for rate-limit violations. Signals that the client has exceeded the permitted request rate and must back off.
HTTP-03-011	MUST	The API MUST return 503 Service Unavailable when it is temporarily unable to handle a request, such as while overloaded, under maintenance, or before the storage it needs is ready. HTTP defines 503 for a server that is temporarily unable to handle the request because of overload or scheduled maintenance, a condition expected to clear after some delay. Vultron inherits that rule. A transient error inside a request the server could handle is not that condition, so it does not draw this code.

Idempotency

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

File ID: ID

Activity ID Uniqueness

ID	Priority	Requirement	Related
ID-01-001	MUST	All activities MUST have globally unique id field (URI) ActivityPub requires every object, activities included, to carry a unique global identifier; ActivityStreams 2.0 alone leaves id optional. Duplicate detection (ID-02) relies on it.

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-001	MUST	The endpoint URL MUST be discoverable from actor profile ActivityPub requires every actor object to carry its inbox property, so a peer finds the endpoint from the profile rather than by a URL convention, which also leaves each deployment free to place it.
IE-02-002	MUST	The endpoint MUST accept activities delivered to it by HTTP POST. ActivityPub delivers an activity to an inbox by HTTP POST. Vultron inherits the rule. That POST is the only method the inbox serves is this codebase's choice (IE-02-005).
IE-02-003	MUST	The endpoint MUST reject non-POST requests with HTTP 405 The inbox is a delivery target, not a mailbox other actors may read: ActivityPub grants an inbox read only to the actor's own authenticated owner, and Vultron has no authentication, so a GET here would open another actor's mail. The 405 covers both trailing-slash forms, and it does not fall out of having no GET route: the profile route is a path catch-all (/{actor_id:path}) that answers 404 to an unrouted GET, so the inbox path needs its own method refusal declared ahead of it.	Depends on: HTTP-03-001

Request Handling

ID	Priority	Requirement	Related
IE-03-001	MUST	The endpoint MUST validate Content-Type header	Depends on: HTTP-01-001
IE-03-003	MUST	Requests exceeding the maximum request body size MUST be rejected with HTTP 413. Rejecting oversized payloads with an explicit 413 prevents resource exhaustion and signals the limit violation to the sender.	Refines: IE-03-002 Depends on: HTTP-02-001 — HTTP-02-001's default limit decides when this 413 applies; HTTP-02-001 keeps only the limit, and the 413 answer stays here (MS-12-010)

Error Responses

ID	Priority	Requirement	Related
IE-07-001	MUST	The endpoint MUST answer with the status code HTTP defines for each transport failure: HTTP 400 for a malformed request, HTTP 405 for a method other than POST, and HTTP 413 for a request body over the size limit.	Depends on: HTTP-03-001

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-001	MUST	Incoming payloads MUST conform to ActivityStreams 2.0 structure

URI Validation

ID	Priority	Requirement	Related
MV-05-001	MUST	The system MUST validate that ID and reference fields contain valid URIs ActivityStreams 2.0 gives every id and every reference as an IRI, so a value that is not one is not a well-formed activity. Vultron inherits the rule.

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-001	MUST	All ActivityStreams object IDs MUST use full URI form ActivityPub requires every object it distributes to carry a publicly dereferenceable URI as its identifier, which a relative or bare identifier is not. ActivityStreams 2.0 alone only says relative references SHOULD NOT be used. Vultron inherits the ActivityPub rule.	Implements: VP-16-002 Implements: VP-16-003
OID-01-002	MUST	IDs MUST be unique within the issuing actor's deployment; cross-deployment uniqueness is achieved by requiring full URI form (OID-01-001) with a deployment-controlled authority component. Restates ActivityPub's identifier rule: an object's URI has an authority belonging to the server that originated it, so that server keeps it unique and uniqueness across deployments follows from the full URI form.

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 Population

ID	Priority	Requirement	Related
OX-02-002	MUST	Each outbox activity MUST conform to ActivityStreams 2.0 structure

Outbox Delivery

ID	Priority	Requirement	Related
OX-03-001	MUST	Activities in an actor's outbox MUST be delivered to recipient inboxes ActivityPub's delivery rule: a server posts each activity in an actor's outbox to the inbox of every addressee. Vultron inherits it.

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

Response Activity Structure

ID	Priority	Requirement	Related
RF-01-001	MUST	Response activities MUST conform to ActivityStreams 2.0

Response Delivery

ID	Priority	Requirement	Related
RF-06-001	MUST	Response activities MUST be delivered to the relevant actors' inboxes ActivityPub delivers every activity to the inboxes of its addressees; a response is no exception. Which actor a response goes to is Vultron's rule (RF-06-002).

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-002	MUST	A receiver MUST cope with an object given either inline or as a URI reference, as ActivityStreams 2.0 allows.

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

Serialization Rules

ID	Priority	Requirement	Related
VM-07-002	MUST	Serialized messages MUST use the ActivityStreams 2.0 property names, which are camelCase, never another spelling such as Python snake_case field names.