Implementation Specification: Vector DERMS

Summary

This implementation specification defines the project-scoped delivery for the Vector DERMS milestone.

It is an incremental delivery plan against the long-lived OSCP and microgrid system designs. It captures the Vector-specific scope, partner-profile constraints, and short-term implementation choices needed to deliver the first OSCP integration without changing the long-term system design direction.

System Design References

• Primary system design: docs/reference/system-design/oscp/spec.md
• Dependent system design: docs/reference/system-design/microgrid.md

Project Goal

Deliver a Vector-compatible OSCP Flexibility Provider integration that binds Vector group_id values to managed microgrid scopes, manages connection configuration and lifecycle, translates incoming forecasts into microgrid OperatingEnvelope constraints, and publishes outbound metering, adjustment, and compliance messages through the OSCP domain.

In Scope

• OSCP configuration entity covering group binding to a managed microgrid scope and connection profile management.
• OSCP operations visibility, registration, handshake, heartbeat, and lifecycle state.
• Protocol-agnostic OperatingEnvelope translation for OSCP forecast effects, initially applied by updating legacy circuit available-capacity values associated with the mapped managed scope when that scope corresponds to a grid-connection circuit.
• Forecast intake and translation into the microgrid OperatingEnvelope boundary.
• Fallback-mode activation, operator visibility, gap-policy application, and intentional disconnect handover for OSCP-managed constraints.
• Outbound group and asset measurement publication through the interim dispatcher.
• Manual adjustment flow and compliance-error publication.
• Vector-specific measurement profile behavior.

Story Scope

• All stories in stories.md in this folder.

Cross-Project Microgrid Dependencies

• Microgrid Provisioning and Management
• External Capability Status to Microgrid Card
• Microgrid Status Summary View
• Manage UI Cycle and Breach Visibility

Vector-Specific Short-Term Variations

• The first rollout uses the Vector partner profile on top of the generic OSCP system design.
• measurement_configuration=INTERMITTENT is required for this project.
• The Vector profile uses UpdateAssetMeasurements as a partner-profile deviation from the canonical Capacity Provider measurement path.
• OAuth Client Credentials and required static header behavior are part of this project scope as partner-profile configuration concerns.
• Quarter-hour aligned metering windows and initial_measure_time behavior are required in this project even though the system design keeps that logic generic.
• The first OperatingEnvelope implementation writes through to legacy circuit available-capacity fields and uses legacy UI surfaces for operator visibility when the managed scope maps to a legacy grid-connection circuit.
• Current delivered OperatingEnvelope scope is limited to active-envelope compatibility projection and deterministic return to the existing non-envelope path on expiry or withdrawal.
• The confirmed fallback treatment uses a yellow operator-visible fallback mode rather than a red fail-safe alarm, while still creating notification and incident context.
• The current supported configurable gap-policy surface exposes only one selectable option: return to the existing circuit safe default or non-OSCP path when no matching fallback block covers now.

Current Delivery Sequencing

• The current lifecycle delivery slice is OSCP configuration, handshake, heartbeat, and visible liveness or error state.
• The next confirmed delivery slice adds fallback-mode activation, gap-policy handling, and intentional disconnect handover on top of the existing lifecycle and forecast path.
• Registration remains in project scope, but it is intentionally scheduled as a later follow-on story because the current Vector testing path and forecast or metering delivery do not depend on registration visibility.

Explicitly Out of Scope for This Project

• Generalized Capacity Optimizer support.
• Broader multi-partner OSCP profile support beyond what is needed for Vector.
• Complex multi-branch load-balancing redesign beyond the explicit OperatingEnvelope story and the listed cross-project dependencies.
• A canonical microgrid operating-envelope history or detail view beyond what is required for the interim legacy-circuit path.
• Additional gap-policy options beyond the current single selectable safe-default option, including dead reckoning or alternate configurable fail-safe policies.

Current Policy Boundary

• COR-19 currently proves that accepted active envelopes affect legacy circuit available-capacity and that expiry or withdrawal returns the circuit to the existing non-envelope path.
• When OSCP heartbeat/liveness is lost and valid fallback forecast coverage exists, BetterFleet must enter yellow fallback mode, apply fallback-derived constraints, and raise operator-visible notification and incident context.
• When primary forecast coverage has a gap, BetterFleet must enter yellow fallback mode; if matching fallback coverage exists it uses that fallback block, otherwise it applies the configured gap policy. The current supported selectable gap policy is the existing circuit safe default or non-OSCP path.
• A user-initiated OSCP disconnect must immediately clear active OSCP forecast and fallback envelopes, return the managed scope to the current non-OSCP path, and show the operator that full local control has been taken back.

Backlog Link

• Future OSCP stories not assigned to this project should be tracked under docs/work/backlog/oscp/stories.md.