System Design: OSCP Flexibility Provider Domain¶

TLDR (Solution Summary)¶

bf-manage-core will implement a separate OSCP Flexibility Provider domain that owns OSCP connection lifecycle, group_id bindings, and protocol message handling, while using the microgrid domain only through protocol-agnostic microgrid contracts.

• OSCP Domain Contract + introduce OscpConnection, OscpGroupBinding, OscpConnectionState, and OscpCapacityForecastEnvelope + keep all OSCP-specific identity and lifecycle outside the microgrid domain.
• Group Binding Model + map external group_id values to canonical microgrid_id + node_id targets in the OSCP domain + allow deterministic protocol routing without polluting microgrid aggregates.
• Connection Lifecycle Contract + define registration, handshake, heartbeat, and offline-state handling aligned to OSCP 2.0 connection sections + make inbound and outbound OSCP conversations implementation-safe.
• Forecast Intake Contract + define how UpdateGroupCapacityForecast messages are received, validated, audited, and translated into generic microgrid-facing OperatingEnvelope inputs + keep protocol semantics outside the microgrid model.
• Outbound Messaging Contract + define AdjustGroupCapacityForecast, GroupCapacityComplianceError, and measurement publication behavior + complete the current supported protocol surface.
• Connection Profile Layer + define how partner-specific protocol deviations are isolated behind OSCP connection configuration + keep the core OSCP domain standards-based and vendor-agnostic.
• Operational Visibility Contract + define OSCP connection status, last-message audit fields, and group-binding observability + support integration operations and troubleshooting.

1. Summary¶

Problem¶

bf-manage-core needs to operate as an OSCP v2.0 Flexibility Provider, but the protocol concerns, external group_id identity, and remote-party lifecycle must not leak into the microgrid domain.

Goal and Design Outcomes¶

• Define the conceptual system design for OSCP v2.0 support in bf-manage-core when acting as a Flexibility Provider.
• Keep OSCP as a separate bounded context that uses microgrid contracts without making microgrid OSCP-aware.
• Define a canonical group_id -> microgrid_id + node_id binding model in the OSCP domain.
• Align core design to OSCP v2.0 protocol sections while allowing partner-specific implementation stories later.
• Design outcomes:
  • OSCP-specific identifiers, state, and protocol rules are owned by the OSCP domain, not by microgrid.
  • Every inbound or outbound OSCP business message resolves to exactly one OSCP connection and one group binding.
  • Forecast, measurement, adjustment, and compliance flows are traceable and operationally auditable.
  • The design remains standards-based even when a narrower partner profile requires a slightly different message profile.

System Capabilities¶

• OSCP Flexibility Provider Domain + define bounded context, actors, commands, events, and policies + provide a protocol-safe domain boundary for OSCP.
• OSCP Group Binding + define canonical storage and lookup of group_id to microgrid_id + node_id mappings + support deterministic routing of all group-scoped messages.
• OSCP Connection Lifecycle + define registration, handshake, handshake acknowledgement, heartbeat, and offline handling + support stable protocol sessions with remote capacity providers.
• OSCP Forecast Translation + define intake of UpdateGroupCapacityForecast and translation to generic microgrid operating-envelope inputs + let OSCP drive site-level constraints without changing microgrid semantics.
• OSCP Outbound Provider Messages + define adjustment requests, compliance error reporting, and measurement publication + complete the current supported Flexibility Provider responsibilities.
• OSCP Connection Profile + define standards-aligned defaults plus isolated per-connection behavior switches + keep partner-specific deviations out of the core domain model.
• OSCP Binding Administration + define administrative APIs and UI for connection and group_id binding management + make provisioning and support operationally manageable from product surfaces.
• OSCP Operations View + define read-side status for connections, group bindings, last forecasts, last measurements, and last failures + support supportability and operational safety.

Scope (In)¶

• OSCP v2.0 Flexibility Provider role semantics.
• OSCP-specific domain language, message handling, connection state, and group binding.
• Conceptual contracts for how OSCP uses microgrid IDs and microgrid-facing generic contracts.
• Protocol-aligned handling of registration, handshake, heartbeat, forecast, adjustment, compliance, and measurements.
• Operational observability for OSCP integration state.

Scope (Out)¶

• Microgrid topology, limit-policy, and balancing internals already covered by the microgrid specification.
• Transport-level implementation details such as exact framework wiring, token storage schema, or deployment infrastructure.
• Partner-specific acceptance criteria and user-story slicing.
• Commercial contract logic, market rules, and non-technical onboarding process details.
• Flexibility Provider communication to individual field devices or chargers.

Future Evolution Guardrails¶

• The design must support one microgrid containing multiple independently managed scopes and multiple future external bindings across those scopes, even though the current supported model uses one active group_id per managed scope.
• The design must not require the microgrid domain to store OSCP identifiers, protocol states, or partner-specific behavior.
• The design must not couple the OSCP domain to one specific external party, even if early implementations target a single DERMS integration.
• The design should remain open to adding the Capacity Optimizer interaction path later without reshaping the core Flexibility Provider model.

2. Users and Use Cases¶

Primary Personas¶

High-Level Use Cases¶

• As an integration engineer, I can bind an external OSCP group_id to one internal microgrid_id + node_id target so that OSCP traffic routes to the right site boundary.
• As an integration engineer, I can manage OSCP connections and group_id bindings through administrative APIs and UI so that provisioning and support do not rely on direct database changes.
• As a remote capacity provider, I can complete registration, handshake, and heartbeat with the Flexibility Provider and know whether the connection is online.
• As a remote capacity provider, I can send a group capacity forecast that is validated, audited, and translated into a generic OperatingEnvelope for the mapped microgrid.
• As the Flexibility Provider, I can publish measurement, adjustment, and compliance messages for a mapped group without exposing microgrid internals directly.
• As support, I can inspect which OSCP connection, group binding, and last protocol exchange affected a given microgrid.

Edge Cases and Failure Modes¶

• A group_id is unknown or resolves to more than one microgrid.
• Registration has not been completed but business messages are received.
• Handshake is incomplete or expired.
• Heartbeats stop and the connection transitions offline.
• A forecast payload is syntactically valid but cannot be translated into a supported microgrid OperatingEnvelope.
• Outbound measurement publication cannot be produced because required source data is unavailable.
• A partner expects a protocol subset or behavior that differs from the default standards-based profile.

3. Conceptual Model Terms and Decisions¶

Key Terms¶

Decision Ledger¶

4. Domain Model and Eventstorming (Conceptual)¶

Bounded Context and Ubiquitous Language¶

• Bounded context: OSCP Flexibility Provider.
• External actors: Capacity Provider, optional future Capacity Optimizer.
• Internal collaborators: Microgrid Domain, Operations / Support, Integration Configuration.
• Core commands: register endpoint, initiate handshake, acknowledge handshake, record heartbeat, receive group capacity forecast, publish measurements, request capacity adjustment, report compliance error, mark connection offline.
• Core events: group bound, registration completed, handshake initiated, handshake acknowledged, heartbeat recorded, connection offline detected, capacity forecast received, operating envelope prepared, measurements published, adjustment requested, compliance error reported.

Eventstorming Diagram¶

flowchart LR
    CP[Capacity Provider]
    OSCP[OSCP Flexibility Provider Domain]
    MG[Microgrid Domain]
    OPS[Operations / Support]

    CP -->|Register / Handshake / Heartbeat| OSCP
    CP -->|UpdateGroupCapacityForecast| OSCP
    OSCP -->|Generic operating envelope| MG
    MG -->|Aggregated measurements / status / breach signals| OSCP
    OSCP -->|UpdateGroupMeasurements / AdjustGroupCapacityForecast / GroupCapacityComplianceError| CP
    OSCP -->|Connection status / audits / binding status| OPS

Connection and Forecast Flow¶

sequenceDiagram
    participant CP as Capacity Provider
    participant OD as OSCP Domain
    participant MG as Microgrid Domain

    CP->>OD: Register / Handshake / Heartbeat
    OD-->>CP: HTTP 204 + HandshakeAcknowledge when required
    CP->>OD: UpdateGroupCapacityForecast(group_id, type, blocks)
    OD->>OD: Resolve group_id to managed microgrid target
    OD->>OD: Validate lifecycle state and payload
    OD->>MG: Apply generic OperatingEnvelope
    MG-->>OD: Accept / reject with generic outcome
    OD-->>CP: HTTP 204
    MG->>OD: Measurement / breach / inability-to-comply signal
    OD->>CP: UpdateGroupMeasurements or profile-required `UpdateAssetMeasurements`
    OD->>CP: GroupCapacityComplianceError when required

Aggregates and Entities (Conceptual)¶

• OscpConnection:
  • Owns remote-party registration state, selected OSCP version, base URL references, required behaviour, and liveness state.
  • Owns whether the connection is currently allowed to exchange business messages.
• OscpGroupBinding:
  • Owns canonical mapping from external group_id to one internal managed target represented as microgrid_id plus optional node_id.
  • Optionally owns measurement-publication strategy and any external reporting identifiers needed for that binding.
• OscpForecastConversation:
  • Owns receipt, correlation, and audit of inbound capacity forecast messages for one group.
  • Owns translation result from OSCP forecast to generic OperatingEnvelope.
• OscpOutboundPublication:
  • Owns audit of outbound measurements, adjustment requests, and compliance errors.
  • Owns correlation to earlier inbound forecasts when required.
• OscpOutboundDispatcher:
  • Claims due outbound publications and performs HTTP delivery to the remote OSCP party.
  • Exists as an interim in-process/background worker until event-bus-driven handler orchestration is available.
• OscpConnectionProfile:
  • Defines the active protocol subset, behaviour switches, and profile-level constraints for one remote integration.
  • Exists to isolate remote-party specifics from the core OSCP domain language.

Connection Profile Configuration (Conceptual)¶

Notes: - auth_mode and related references are conceptual configuration fields only; credential storage mechanics remain out of scope for this specification. - measurement_publication_mode is a local OSCP connection-profile setting, not a standard OSCP discovery flag. - measurement_configuration aligns to standard OSCP handshake RequiredBehaviour semantics and describes aggregation behaviour, not whether measurement publication is enabled. - The current supported measurement semantics use INTERMITTENT mode, representing bounded-window energy totals and peak instantaneous load rather than an ever-increasing cumulative meter value. - measurement_publication_interval_seconds is a local OSCP scheduling setting. It defines cadence, not message semantics.

HTTP and Header Semantics (Normative)¶

1. Every outbound OSCP request must include Authorization and X-Request-ID.
2. Every outbound OSCP message that replies to or reports against an earlier OSCP message must include X-Correlation-ID.
3. Valid synchronous OSCP responses must return HTTP 204 with no payload.
4. Error responses may return another HTTP status code and may include a human-readable payload; if the error relates to an earlier message, X-Correlation-ID should be preserved.
5. Handshake and HandshakeAcknowledge must each receive HTTP 204 before the follow-up OSCP message is considered accepted.
6. The current supported model does not support segmented OSCP messages; inbound segmented requests are rejected as unsupported and outbound segmented requests are not emitted.

Required Behaviour Negotiation (Normative)¶

1. Each connection profile defines the local desired RequiredBehaviour.
2. Each received Handshake or HandshakeAcknowledge captures the remote required behaviour for audit.
3. The connection stores an effective negotiated behaviour derived from local profile rules and the latest accepted remote requirements.
4. Business messaging is allowed only when the effective negotiated behaviour is valid for the local connection profile.
5. A handshake with unacceptable required behaviour must be rejected with protocol-appropriate error handling and visible audit state.

Measurement Configuration Semantics (Current Supported Model)¶

Notes: - When INTERMITTENT is used, the bounded measurement window is defined by the active connection profile. - When INTERMITTENT is used, energy measurement values represent total consumption during the configured window and instantaneous measurement values represent the maximum point load during that same window.

Invariants and Business Rules (Normative)¶

1. group_id binding ownership belongs to the OSCP domain; the microgrid domain must not store OSCP identifiers.
2. Each active group_id resolves to exactly one microgrid_id + node_id target in the current supported model.
3. Business messages must not be processed for an unregistered or invalidly handshaken connection.
4. Offline state must block business messaging until connection lifecycle rules are satisfied again.
5. Every accepted UpdateGroupCapacityForecast must be auditable to one connection, one group binding, and one translation outcome.
6. OSCP message handling must preserve request and correlation identifiers where present.
7. OSCP message timestamps must follow OSCP time requirements and retain timezone information.
8. The OSCP domain may translate protocol messages into generic microgrid operations, but the microgrid domain must not be required to understand OSCP sections, roles, or message names.
9. Outbound compliance errors must correlate to an earlier forecast when protocol rules require it.
10. Measurement publication strategy is determined by OSCP connection and group-binding configuration, not by the microgrid domain.
11. In the current supported model, an active managed scope may be managed by only one active OSCP connection and one active OSCP group_id.
12. Every OSCP connection profile must define auth_mode, measurement_publication_mode, measurement_configuration, and measurement_publication_interval_seconds.
13. The current supported measurement publication model uses INTERMITTENT measurement configuration.
14. Until event-bus-driven handlers are available, outbound OSCP messages must be executed from persisted outbound-publication records by an in-process/background dispatcher within bf-manage-core.
15. When a message relates to an earlier OSCP message, correlation metadata must be retained and reused in outbound transport headers where required.
16. When the active Capacity Provider connection is offline or capacity updates are no longer being received, the Flexibility Provider must use fallback capacity from the latest accepted forecast until the online condition is restored.
17. When online state is restored, the OSCP domain must reactivate the latest non-fallback forecast state unless superseded by a newer accepted forecast.
18. UpdateAssetMeasurements remains a profile-based deviation for CP-facing integration; UpdateGroupMeasurements is the canonical Capacity Provider path.
19. Authentication or session material may be retained for transport security and request routing, but it must not be the primary mechanism that enforces active group_id, microgrid_id + node_id, or OSCP-connection uniqueness.
20. After authentication succeeds, every inbound OSCP business message must resolve through persisted OSCP connection state and active group-binding state before it can affect microgrid behavior.

Protocol Alignment (Normative Reference Map)¶

5. Requirements and Constraints¶

Functional Requirements¶

• FR-001: The system shall implement an OSCP Flexibility Provider bounded context separate from the microgrid domain.
• FR-002: The system shall store and manage group_id -> microgrid_id + node_id bindings in the OSCP domain.
• FR-003: The system shall support OSCP registration, handshake, handshake acknowledgement, heartbeat, and offline-state handling for the Flexibility Provider role.
• FR-004: The system shall receive and validate UpdateGroupCapacityForecast messages for bound groups.
• FR-005: The system shall translate accepted OSCP forecasts into generic microgrid-facing OperatingEnvelope inputs without requiring the microgrid domain to understand OSCP semantics.
• FR-006: The system shall support outbound AdjustGroupCapacityForecast messages for a bound group.
• FR-007: The system shall support outbound GroupCapacityComplianceError messages for a bound group and correlate them to the relevant earlier forecast when required.
• FR-008: The system shall support outbound measurement publication for a bound group according to the active OSCP connection profile.
• FR-009: The system shall retain auditable metadata for inbound and outbound OSCP messages, including connection, binding, request, and correlation references.
• FR-010: The system shall expose operational read models for OSCP connections, OSCP group bindings, and last successful / failed protocol exchanges.
• FR-011: The system shall allow standards-aligned connection behavior to be configured separately from any partner-specific profile switches.
• FR-011a: The system shall allow each OSCP connection profile to configure measurement_publication_mode with supported values GROUP and ASSET.
• FR-011b: The system shall allow each OSCP connection profile to configure measurement_configuration using OSCP-supported values, with INTERMITTENT as the current supported configuration.
• FR-011c: The system shall allow each OSCP connection profile to configure measurement_publication_interval_seconds to drive outbound measurement-publication scheduling.
• FR-011d: The system shall allow each OSCP connection profile to configure conceptual auth settings including auth mode, credential reference, and optional static-header profile reference.
• FR-012: The system shall reject or quarantine messages that cannot be resolved to a valid active group binding.
• FR-013: The system shall use OSCP-standard endpoint semantics and message families as the canonical conceptual contract, even when a partner profile uses only a subset or requires an adapted publication strategy.
• FR-014: The system shall provide administrative APIs and UI for creating, updating, disabling, and inspecting OSCP connections, connection profiles, and group_id -> microgrid_id + node_id bindings.
• FR-015: The system shall enforce current supported active-binding cardinality of one group_id, one microgrid_id + node_id target, and one active OSCP connection per managed target.
• FR-016: The system shall persist outbound OSCP publications before delivery and execute them through an interim OscpOutboundDispatcher within bf-manage-core until a deployed event bus is available.
• FR-017: The system shall enforce OSCP header and response semantics for Authorization, X-Request-ID, X-Correlation-ID, and HTTP 204 success responses.
• FR-018: The system shall reject segmented OSCP messages in the current supported model and record deterministic audit outcomes for that rejection.
• FR-019: The system shall store both the latest accepted primary forecast and its fallback-capacity semantics so the mapped microgrid can be constrained safely during CP offline conditions.
• FR-020: The system shall repeat compliance-error reporting when a newly received forecast still cannot be met and shall treat absence of a renewed compliance error after a new forecast as compliance restored.

Non-Functional Requirements¶

• NFR-001: OSCP-specific data and microgrid-specific data must remain in separate bounded contexts.
• NFR-002: Message handling must be idempotent enough to tolerate retries of the same inbound protocol exchange without unsafe duplicate side effects.
• NFR-003: Connection status and last-message audit data must be operationally visible without requiring protocol log inspection.
• NFR-004: The design must allow additional OSCP roles or profiles later without redesigning the microgrid domain.
• NFR-005: Forecast translation outcomes must be reproducible and diagnosable from stored audit data.
• NFR-006: Time handling must preserve timezone offsets and remain compliant with OSCP time-format rules.
• NFR-007: The design must support secure connection credential handling, but credential-storage implementation details are outside this spec.
• NFR-008: Interim outbound OSCP dispatch must support retry, audit, and deterministic send-state visibility without requiring a deployed event bus.
• NFR-009: OSCP admin and operations views must expose enough connection-profile and audit detail to distinguish standards-based behavior from partner-profile deviations without reading transport logs.

Constraints¶

• C-001: The microgrid domain must not store group_id, OSCP connection state, OSCP lifecycle timestamps, or partner-specific endpoint behavior.
• C-002: The OSCP domain must not duplicate microgrid topology, limit-policy, or balancing models already defined in the microgrid specification.
• C-003: The current supported model is limited to the Flexibility Provider role and does not require full Capacity Optimizer support.
• C-004: Standards-based OSCP references must be cited by OSCP section number; this specification must not duplicate OSCP schema definitions.
• C-005: Partner-specific integration behavior must be expressed as connection-profile configuration or later story detail, not as core protocol semantics.

Assumptions¶

• A-001: Current supported routing resolves one OSCP group_id to one managed microgrid_id + node_id target, typically the whole microgrid or one GRID_CONNECTION subtree, managed by one active OSCP connection.
• A-002: The microgrid domain will provide protocol-agnostic contracts for applying OperatingEnvelope inputs and reading aggregated operational state.
• A-003: The first implementation stories may target a narrower partner profile than the full standards-based conceptual surface, but the conceptual model remains protocol-generic.

6. Interaction and Flow¶

Connection Lifecycle¶

1. A connection is provisioned with a connection profile and one or more group bindings.
2. Registration establishes selected version and authenticated endpoint relationship.
3. Handshake and handshake acknowledgement exchange required behaviour such as heartbeat interval and measurement configuration.
4. Heartbeats maintain liveness.
5. Missing heartbeats or equivalent liveness failure transition the connection offline.
6. Offline connections must re-satisfy lifecycle rules before business messaging resumes.

Forecast Intake¶

1. The OSCP domain receives UpdateGroupCapacityForecast.
2. The OSCP domain validates lifecycle state, version, identifiers, timestamps, and message shape against OSCP rules.
3. The OSCP domain resolves group_id to one managed microgrid_id + node_id target.
4. The OSCP domain translates forecast blocks and forecast type into a generic operating envelope.
5. The OSCP domain stores both the primary forecast state and any fallback-capacity semantics required to operate safely during offline conditions.
6. The OSCP domain submits the translated envelope through a protocol-agnostic microgrid boundary.
7. The translation result and resulting correlation metadata are stored for audit and later compliance/error reporting.

Offline and Fallback Behaviour¶

1. The latest accepted forecast conversation retains the normal capacity state plus its fallback-capacity semantics.
2. When the active Capacity Provider connection transitions offline or forecast validity can no longer be guaranteed, the OSCP domain activates fallback-derived OperatingEnvelope constraints for the mapped microgrid.
3. While offline, the Flexibility Provider continues to operate against the fallback-derived envelope until online state is restored.
4. When the connection is restored through handshake/liveness recovery, the OSCP domain reactivates the latest accepted non-fallback forecast state unless a newer accepted forecast supersedes it immediately.
5. Offline/fallback transitions and restored-normal transitions are auditable in the OSCP operations view.

Measurement Publication¶

1. The OSCP domain determines whether a measurement publication is due under the active connection profile using measurement_publication_interval_seconds.
2. The OSCP domain reads the required aggregated or profile-derived measurement inputs from microgrid-facing or related read models.
3. The OSCP domain serializes the outbound measurement message using the active publication strategy:
4. canonical default: UpdateGroupMeasurements
5. profile-based deviation: UpdateAssetMeasurements where a partner profile explicitly requires it
6. The publication is persisted as an OscpOutboundPublication and marked due for dispatch.
7. The interim OscpOutboundDispatcher claims the due publication, sends it to the remote party, and updates delivery audit metadata.

Adjustment and Compliance Reporting¶

1. A need for additional or reduced capacity is detected outside or at the boundary of the OSCP domain.
2. The OSCP domain resolves the affected group binding.
3. The OSCP domain builds AdjustGroupCapacityForecast or GroupCapacityComplianceError payloads aligned to OSCP rules.
4. GroupCapacityComplianceError publications must correlate to the relevant forecast using stored request/correlation metadata.
5. If a newer forecast is received and the site still cannot comply, a new compliance-error publication must be emitted against that newer forecast.
6. The publication is correlated to the relevant forecast or decision context, persisted as an outbound publication, and dispatched by the interim OscpOutboundDispatcher.

State Model¶

7. Relationship to the Microgrid Specification¶

• This specification uses the microgrid system design as the source of truth for site-level electrical behavior and operating state.
• This specification does not redefine topology, limits, balancing logic, or capability-status semantics already owned by microgrid.
• This specification only defines how the OSCP domain binds to a microgrid and exchanges protocol messages around that boundary.

8. Long-Term Evolution Notes¶

• The interim OscpOutboundDispatcher is an allowed medium-term solution until event-bus-based orchestration is deployed, provided the same persisted outbound-publication audit contract is preserved.
• Additional OSCP roles, multi-binding profiles, and broader partner-profile support may be introduced later without requiring changes to the microgrid domain boundary.
• Transport credential storage, deployment wiring, and framework-specific HTTP adapter details remain implementation concerns outside this system-design document.