contract_id: CONTRACT-DORA-MAJOR-INCIDENT-REPORT-V1-025 schema_version: dora-major-incident-report.v1 status: Draft owner: Notify platform schema_reviewer: maintainer-of-record review_cadence: per-stella-minor-release-and-on-official-schema-change legal_sources:

DORA Major Incident Report Contract v1

Part of the Stella Ops Contracts index. Audience: implementers and reviewers working on the Notify DORA major-incident report encoder, its outbound channel, the CLI verbs, and the Export Center assurance profile. Related: DORA Incident Classification v1 supplies the seven classification criteria consumed here.

Purpose

This contract defines the deterministic Stella Ops export shape for DORA major ICT-related incident reports. The v1 encoder (DoraMajorIncidentReportEncoder.EncodePackage) emits:

The produce-and-sign handoff (DoraMajorIncidentOutboundChannel.ProduceAsync) additionally emits, alongside the above:

The contract is a produce-and-sign handoff surface. It does not submit directly to a competent authority and does not call live regulator endpoints; an optional, default-off, fails-closed auto-submit path is available only through a caller-supplied submitter (see Outbound Channel And Optional Auto-Submit).

Evidence scope is split:

Schema Pinning

The local taxonomy package marker is not an EBA DPM/XBRL package. EBA-published schema validation is blocked until the exact EBA DPM/XBRL taxonomy package is vendored in-repo or in an offline runtime-assets location, with version and license review recorded. The encoder must not fetch schemas at runtime or test time.

Report Variants

VariantFile prefixIntended cadence
initial_reportinitial-reportHours-class initial DORA report
intermediate_reportintermediate-reportNo later than 72 hours
final_reportfinal-reportNo later than one month

Each variant carries the same core report context:

Severity and status are normalised to lower-case; the LEI, jurisdiction code, competent-authority code, and currency codes are normalised to upper-case during encoding (DoraMajorIncidentReportValidator.NormalizeReporter / NormalizeIncident).

Final reports require endedAt, rootCauseSummary, and remediationSummary. Initial and intermediate reports may carry empty final fields while the investigation is active.

XBRL Shape

The local XBRL artifact root is:

<xbrli:xbrl
  xmlns:xbrli="http://www.xbrl.org/2003/instance"
  xmlns:dora="urn:stellaops:dora:major-incident-report:v1"
  contractVersion="dora-major-incident-report.v1"
  legalTemplateVersion="dora-major-incident-report-eu-2025-302"
  taxonomyPackageVersion="dora-major-incident-report-eu-2025-302-local-contract-v1">
  ...
</xbrli:xbrl>

The deterministic child order is:

  1. dora:reportContext
  2. dora:reportingEntity
  3. dora:incident
  4. dora:timeline
  5. dora:classification
  6. dora:evidence

dora:reportContext carries reportId, tenantId, reportVariant, generatedAt, operatorApprovalRef, reportingContentLegalBasis, and reportingTemplateLegalBasis. dora:reportingEntity carries lei, jurisdictionCode, and isFinancialEntity as attributes plus legalEntityName, competentAuthorityCode, and complianceProfileRef facts. dora:classification carries schemaVersion, legalBasis, and isMajorIncident attributes, the classifiedAt/classifiedBy facts, seven dora:criterion elements (each with a name and thresholdMet attribute and its criterion-specific dora:field children), and a dora:classificationEvidenceRefs block. Empty optional values are emitted as empty elements/attributes rather than being omitted.

Note: the local-validation pass only asserts the presence of reportContext, reportingEntity, incident, classification, and evidence (see DoraMajorIncidentReportValidator.ValidateXbrl); dora:timeline is always emitted by the encoder but is not separately re-checked by the post-encode validation.

The local iXBRL artifact is XHTML with ix:nonNumeric facts for the primary report context (reportId, reportVariant, generatedAt, tenantId, LEI, legal name, incident id, incident title, isMajorIncident) and the seven criterion thresholdMet facts.

Envelope Shape

Each generated envelope is compact JSON with deterministic property order. The envelope file itself is served with media type application/vnd.stellaops.dora-major-incident-report.v1+json (DoraMajorIncidentReportConstants.EnvelopeMediaType); the mediaType values inside the envelope describe the referenced artifacts. evidenceRefs is sorted ordinally and is never empty (at least one immutable reference is mandatory — see Local Validation). The ebaPublishedSchemaValidation.evidence array is populated with the fixed checklist below, not left empty:

{
  "contractVersion": "dora-major-incident-report.v1",
  "legalTemplateVersion": "dora-major-incident-report-eu-2025-302",
  "taxonomyPackageVersion": "dora-major-incident-report-eu-2025-302-local-contract-v1",
  "reportVariant": "initial_report",
  "reportId": "dora-report-20260430-001-initial-report",
  "tenantId": "tenant-bank-de",
  "incidentId": "incident-dora-payments-001",
  "generatedAt": "2026-04-30T10:15:00.000Z",
  "operatorApprovalRef": "approval://tenant-bank-de/dora/incident-dora-payments-001/initial-report",
  "xbrl": {
    "fileName": "initial-report.xbrl.xml",
    "mediaType": "application/xbrl+xml",
    "sha256": "sha256:<64 lowercase hex>"
  },
  "inlineXbrl": {
    "fileName": "initial-report.ixbrl.xhtml",
    "mediaType": "application/xhtml+xml",
    "sha256": "sha256:<64 lowercase hex>"
  },
  "evidenceRefs": [
    "cas://evidence/dora/incident-dora-payments-001/classification.json",
    "ledger://authority/audit/dora-approval-001",
    "ledger://notify/dora/opened/incident-dora-payments-001"
  ],
  "localValidation": {
    "status": "passed",
    "ruleSetVersion": "dora-major-incident-report-local-validation-v1"
  },
  "ebaPublishedSchemaValidation": {
    "status": "blocked",
    "reason": "No pinned EBA DPM/XBRL taxonomy or XSD package is present in the local repository scope; external schema fetches are disabled for this sprint.",
    "evidence": [
      "Checked local sprint paths: docs/contracts, devops/runtime-assets, src/Notify, docs/samples/dora-incident-report.",
      "Deterministic local contract validation uses dora-major-incident-report-local-validation-v1 until the exact EBA package is pinned and licensed.",
      "No EBA-published DORA major-incident report taxonomy package or XSD is vendored locally."
    ]
  }
}

Note on localValidation: in the encoded envelope this object exposes only status and ruleSetVersion. The in-memory DoraMajorIncidentLocalValidationResult also carries an Errors list, but that list is not serialised into the envelope (it is only thrown as a DoraMajorIncidentReportValidationException when validation fails).

DSSE Signing And Handoff Manifest

The “produce-and-sign” surface wraps the unsigned envelope in a DSSE envelope and emits a handoff manifest so the bundle can be verified offline.

The internal DSSE MAC is computed through the central ICryptoHmac abstraction so a GOST/SM tenant can verify its own region-correct wrapper; the regulator-bound qualified (eIDAS) signature is a separate plugin step and is not produced here.

Outbound Channel And Optional Auto-Submit

DoraMajorIncidentOutboundChannel.ProduceAsync is the filesystem-drop / optional-submit orchestrator (StellaOps.Notify.Connectors.Dora):

This contract does not call live regulator endpoints; an actual submission is delegated to a caller-supplied IDoraMajorIncidentReportSubmitter.

CLI Surface

The CLI (StellaOps.Cli, DoraIncidentCommandGroup) exposes:

(The exact parent-command wiring for the dora-incident-report export/verify subcommands is defined where BuildDoraIncidentReportExportCommand / BuildDoraIncidentReportVerifyCommand are registered.)

Export Center Assurance Profile

Export Center registers a DORA major-incident assurance profile (AssuranceExportProfileRegistry, profile id dora.major-incident-report, schema dora-major-incident-report.v1, CLI verbs stella export dora-incident-report / stella verify dora-incident-report). Signed export readiness is gated by reason codes (dora-major-incident-report-source-missing, dora-major-incident-report-owner-approval-missing, dora-major-incident-report-schema-mapping-missing) until source inputs, owner approval, and the official EBA schema mapping are supplied.

POST /v1/exports/assurance/profiles/dora.major-incident-report/runs is registered on the shared Assurance produce surface. While readiness is blocked, it returns HTTP 409 assurance_export_readiness_blocked with the reason codes above. A readiness-satisfying request supplies { "doraMajorIncidentReport": { "report": <DoraMajorIncidentReportInput>, "channel": <AssuranceProduceNotifyChannelInput>, "producedAt": "..." } }. ExportCenter maps the JSON-friendly channel DTO into the real Notify NotifyChannel contract, invokes the Notify DORA major-incident encoder and outbound-channel handoff, and stores a deterministic wrapper bundle with media type application/vnd.stellaops.dora-major-incident-report.http-bundle.v1+json. Signing material is still sealed operator configuration under Export:Assurance:DoraMajorIncidentReport (SigningKeyFile / SigningKey and SigningKeyId) and is never accepted from the request body.

Local Validation

Validation runs in two phases. DoraMajorIncidentReportValidator.Validate (invoked via NormalizeAndValidate at the top of EncodePackage) fails closed on the input before any artifact is built; ValidatePackage re-checks the encoded artifacts after they are produced. Both phases throw DoraMajorIncidentReportValidationException (an ArgumentException) carrying the collected Errors.

The input phase fails closed when:

The artifact phase (ValidatePackage) additionally fails closed when:

EBA Schema Validation Status

Blocked for sprint docs-archive/implplan/SPRINT_20260430_112_Notify_dora_rts_encoder.md (now archived). The blocked status is surfaced in every envelope as ebaPublishedSchemaValidation.status = "blocked" (DoraMajorIncidentReportConstants.EbaPublishedSchemaValidationStatus).

Evidence: no pinned EBA DPM/XBRL taxonomy or XSD package is present in the local sprint scope checked for this implementation (docs/contracts, devops/runtime-assets, src/Notify, and docs/samples/dora-incident-report). The implementation ships deterministic local XBRL/iXBRL/envelope validation, DSSE signing, handoff manifest, offline CLI verify, and adjacent tests. A follow-up must vendor the exact EBA package, record its version and license review, and add offline schema-validation tests before the EBA-published schema validation criterion can move to DONE.

Determinism And Offline Replay