StellaOps Contracts

Formal contract specifications for the cross-module interfaces of the StellaOps release control plane. Each contract pins the data models, APIs, schemas, and integration points that modules depend on, so teams can build against a stable shape rather than another module’s current code.

Audience: implementers and reviewers who consume or produce a cross-module interface, and planners who need to know which contracts unblock which sprint tasks.

The repository under src/ is the source of truth. Contracts are reconciled against code in passes but can lag; where a contract and the code disagree, the code wins. Many documents below carry an inline reconciliation note pointing at the verifying source files.

Purpose

Contracts serve as the authoritative reference for:

• Data model definitions (request/response shapes)
• API endpoint specifications
• Integration requirements between modules
• Dependency documentation for sprint planning

Contract Index

Additional Contracts & Decisions

The following contract and decision documents also live in this directory. The status column reflects each document’s own status header; — indicates the document declares no explicit status field.

Contract Categories

Core Data Models

• Advisory Key - Vulnerability ID canonicalization
• VEX Lens - VEX observation correlation
• Risk Scoring - Finding prioritization

Air-Gap / Offline

• Mirror Bundle - Bundle format for offline transport
• Sealed Mode - Sealed environment operation
• Asset Inventory Sync v1 - Deterministic offline/federated Asset Registry event delta bundle

Security / Attestation

• Verification Policy - Attestation verification rules
• Crypto Provider Registry - Pluggable crypto
• Product Update Manifest v1 - Signed Stella release image, SBOM, support, and advisory-fix manifest
• EU Signing Payload Registry v1 - EU compliance DSSE payload media types, schema pins, signer profiles, and offline verifier behavior
• Stella Product CSAF Advisory v1 - Stella-as-manufacturer CSAF 2.0 advisory source model, canonical export, and offline DSSE verification contract
• OpenPGP Encryption Provider v1 - OpenPGP public-key email encryption provider boundary and ciphertext hash evidence contract

Policy Management

• Policy Studio - Policy editing and compilation
• Authority Effective Write - Policy attachment
• NIS2 Control Register v1 - NIS2 Article 21 control register schema
• NIS2 SoA v1 - Statement of Applicability export shape
• NIS2 Effectiveness Report v1 - Monthly 13-area effectiveness report bundle and offline verifier contract

Telemetry

• NIS2 KPI Telemetry Schema v1 - Thirteen-area NIS2 KPI metric naming, labels, and thresholds

Incident Reporting

• DORA Incident Classification v1 - Seven-criteria DORA ICT incident classification facts
• DORA Major Incident Report v1 - Deterministic DORA major-incident XBRL/iXBRL report envelope
• DORA Info Sharing Event v1 - STIX 2.1-aligned DORA Article 45 sharing batch
• ENISA Incident Reporting v1 - Deterministic CRA Article 14 ENISA SRP handoff envelope
• NIS2 Incident Report Envelope v1 - Deterministic NIS2 Article 23 CSIRT/NCA handoff envelope

Register Reporting

• DORA Register of Information v1 - Deterministic local B.01-B.14 RoI projection and bundle index contract

TLPT

• TLPT Scope v1 - Deterministic white-team scoping document for DORA TLPT preparation
• TLPT Baseline v1 - Replay manifest for freezing TLPT feed, policy, dependency graph, and asset state
• TLPT Evidence Pack v1 - Long-lived signed EvidenceLocker capsule for DORA TLPT evidence packs

Export

• Export Bundle - Scheduled export jobs
• CRA Technical File v1 - Deterministic CRA Annex VII technical documentation bundle index with DSSE default, optional cadenced envelope, and regulatory audit ledger recording
• CRA Conformity Dossier v1 - Deterministic CRA conformity-assessment dossier overlays for Module A, B+C, and H
• Standards Mapping v1 - Deterministic ISO/IEC/ETSI/JRC standards mapping bundle
• NIS2 Effectiveness Report v1 - Deterministic signed monthly NIS2 effectiveness JSON bundle

Tenancy / Database

• Findings Ledger RLS - Row-Level Security and partitioning

SDK & API Governance

• API Governance Baseline - OpenAPI freeze and SDK generation
• EU Runtime API Contracts v1 - Graph asset registry runtime APIs and source-service client boundaries

Scanner

• Scanner PHP Analyzer - PHP language analyzer bootstrap
• Scanner Surface - Surface analysis framework
• SBOM Scope Property Registry v1 - stellaops.scope.* declared→deployed component properties

Reachability / Evidence

• RichGraph v1 - Function-level reachability graph schema

Related Resources

API Documentation

• Policy API
• Graph API

Module Architecture

• Excititor Architecture
• Policy Engine Architecture
• Attestor Architecture
• AirGap Documentation

JSON Schemas

The Attestor schema paths below are relative to the monorepo root (the src/ tree); they resolve in a full source checkout but not in a docs-only mirror.

• Verification Policy Schema
• Risk Profile Schema

The Mirror Bundle has no standalone JSON Schema; its canonical shape is defined inline in Mirror Bundle.

Contract Lifecycle

1. Draft - Contract under development
2. Published - Contract is stable and ready for implementation
3. Deprecated - Contract is being phased out
4. Retired - Contract is no longer valid

Contributing

When updating contracts:

1. Increment version number
2. Update Last Updated date
3. Document breaking changes
4. Update Unblocks section if tasks change
5. Add cross-references to related contracts

Sprint Integration

Contracts unblock BLOCKED tasks in sprint files. When a contract is published:

1. Update the sprint file task status from BLOCKED to TODO
2. Add note: Unblocked by CONTRACT-xxx (docs/contracts/xxx.md)
3. Remove the blocked reason