Vector DERMS Deliverables (Stories)¶

Context Summary¶

Product area: BetterFleet Manage.
Primary systems: bf-manage-core (OSCP domain, admin APIs, jobs, dispatcher, and the microgrid OperatingEnvelope boundary), bf-manage-web (management and operations UX), a Vector-compatible mock Capacity Provider for protocol testing, and bf-depot-sim or seeded site scenarios for demonstrable microgrid effects.
Scope basis: docs/work/active/vector-derms/spec.md.
Delivery intent: thin, demonstrable slices where progress is visible either in the UI or via externally driven protocol behavior that causes a visible UI change. No story exists solely to expose an admin or protocol API without a usable or observable outcome.
Immediate delivery priority: establish OSCP binding and connection profile management, make handshake and heartbeat lifecycle state visible, prove that translated OperatingEnvelope data updates the legacy load-balancing path, and then demonstrate forecast intake and outbound publication flows end-to-end.
Deferred follow-up note: workspace/provider separation for OSCP registration and configuration is intentionally out of scope for this pass and should be shaped later as separate work rather than partially folded into the current urgent Vector stories.
Deferred follow-up note: registration and registration-status visibility remain later project scope for the current Vector delivery plan rather than part of the first lifecycle slice.
Confirmed follow-up note: OSCP timeout and forecast-gap handling now enter a yellow fallback mode with notification and incident context rather than a red fail-safe alarm.
Confirmed follow-up note: intentional OSCP disconnect immediately clears active OSCP constraints and returns control to the current non-OSCP path with explicit operator handover messaging.

OSCP Binding and Connection Profile Management¶

Linear issue: COR-15

User Story¶

As an integration engineer, I want to create an OSCP configuration in Manage UI that binds an external group_id to a managed microgrid scope and stores the connection profile against that same OSCP entity so that protocol traffic and connection behavior are provisioned together deterministically.

Dependencies¶

Microgrid Provisioning and Management

Implementation Note¶

Persistence for this initial OSCP configuration slice should use an event-sourced aggregate so binding/profile changes are auditable and configuration history can be reconstructed cleanly.

Acceptance Criteria¶

Manage UI provides list, detail, create, edit, enable, and disable flows for OSCP configuration entities that own both group binding and connection profile data.
Configuration creation resolves candidate microgrids and managed scopes from the canonical microgrid read contract rather than free-text IDs.
A configuration stores external group_id, selected microgrid, selected managed scope, endpoint base URL, selected OSCP version, conceptual authentication references, measurement_publication_mode, measurement_configuration, and measurement_publication_interval_seconds.
When measurement_publication_mode=ASSET, the profile or its related binding requires a reporting asset identity before the connection can be enabled.
The system enforces active uniqueness of one group_id, one managed scope, and one active OSCP connection.
A Vector-targeted connection profile shows measurement_configuration=INTERMITTENT and a 15-minute publication interval as the default demonstrable profile settings.
Saving a valid configuration shows it in the UI with deterministic CONFIGURED state, visible binding details, and no protocol activity yet.

Registration Flow and Status Visibility¶

Linear issue: COR-16

User Story¶

As an integration engineer, I want enabling an OSCP connection to trigger registration and show registration status in Manage UI so that I can confirm the remote endpoint relationship before handshake begins.

Dependencies¶

OSCP Binding and Connection Profile Management
External Capability Status to Microgrid Card

Sequencing Note¶

Later workspace/provider separation is still expected to reshape how registration configuration is provisioned.
For the current Vector delivery plan, registration remains a later project slice rather than part of the first handshake and heartbeat lifecycle demonstration.

Acceptance Criteria¶

Manage UI provides an OSCP connection lifecycle list and detail view for configured connections.
Each connection detail shows connection state, bound group_id, linked microgrid_id, linked managed scope, active measurement mode or configuration, and last outbound publication summary.
Empty-state, disabled-state, and registration-failed views are rendered deterministically.
The view can deep-link to the related Microgrid card or legacy circuit surface for the mapped microgrid.
Enabling a valid OSCP connection persists an outbound registration publication before any network delivery occurs.
The interim dispatcher sends the registration request to a Vector-compatible mock Capacity Provider and records the outcome.
A successful registration updates the UI to REGISTERED and shows selected version, last registration time, and last outbound publication status.
A failed registration remains visible in the UI with retry and audit information and does not lose the persisted outbound record.

Handshake Flow and Negotiated Behaviour Visibility¶

Linear issue: COR-17

User Story¶

As a support operator, I want OSCP handshake activity to move a configured OSCP connection into a visible negotiated state so that I can confirm the connection is ready for liveness management and business messaging.

Dependencies¶

OSCP Binding and Connection Profile Management

Acceptance Criteria¶

An inbound handshake from a Vector-compatible mock Capacity Provider receives the required HTTP response and results in visible handshake audit on the OSCP connection detail.
The corresponding handshake acknowledge is persisted and delivered through the interim outbound dispatcher with visible outbound status.
A successful handshake updates the UI to HANDSHAKEN.
The UI shows the effective negotiated behaviour for heartbeat interval and measurement configuration from the latest accepted handshake exchange.
A handshake with unacceptable required behaviour or equivalent protocol rejection remains visible in the UI with deterministic failure audit and does not move the connection into a business-messaging-ready state.

Heartbeat Flow and Liveness Visibility¶

Linear issue: COR-18

User Story¶

As a support operator, I want OSCP heartbeat activity to move the connection between visible liveness states so that online and offline behavior is clear.

Dependencies¶

Handshake Flow and Negotiated Behaviour Visibility

Acceptance Criteria¶

Once the connection is handshaken, outbound heartbeat publications are created at the configured cadence and their last-send result is visible in the UI.
Receiving valid inbound heartbeats or equivalent liveness confirmations updates the UI to ONLINE and shows the last-heartbeat time.
Missing inbound heartbeats or equivalent liveness failures move the connection to OFFLINE with visible last-heartbeat and offline-threshold information.
The UI distinguishes HANDSHAKEN, ONLINE, and OFFLINE states deterministically so support users can tell whether the connection is ready, live, or offline without reading logs.
When liveness is restored after an offline period, the connection returns to visible online state without losing prior heartbeat and offline audit context.

Operating Envelope Updates Legacy Circuit Capacity for Managed Scope and Legacy UI¶

Linear issue: COR-19

User Story¶

As an operations user, I want a translated OperatingEnvelope to update the legacy circuit available-capacity path for a mapped managed scope so that OSCP forecast effects can be demonstrated immediately using the existing load-balancing path and legacy UI.

Dependencies¶

Microgrid Provisioning and Management

Scope Note¶

COR-19 covers acceptance, activation, expiry, and withdrawal of a translated OperatingEnvelope through the legacy circuit available-capacity compatibility path.
It does not own fallback-mode activation, configurable gap-policy application, or intentional disconnect handover. Those behaviours are follow-on delivery stories built on top of the confirmed COR-19 compatibility path.

Acceptance Criteria¶

Submitting a valid OperatingEnvelope for a selected managed scope updates the legacy circuit available-capacity value associated with that scope when the scope maps to one grid-connection circuit.
Triggering rebalance or equivalent legacy load-balancing evaluation while the envelope is active results in a visible outcome that respects the updated available-capacity value for that managed scope.
The legacy UI surface associated with that circuit shows the changed available-capacity effect without requiring a new dedicated microgrid envelope view.
Submitting an OSCP forecast that cannot be resolved to a valid managed-scope target is rejected with deterministic validation feedback and does not change visible legacy circuit state.
When an active envelope expires or is withdrawn, the legacy circuit available-capacity value returns deterministically to the current non-envelope path for that circuit.

Forecast Intake to Microgrid Constraint and UI Effect¶

Linear issue: COR-20

User Story¶

As a Vector-targeted Capacity Provider, I want an OSCP group forecast to be accepted, translated, and surfaced in OSCP operations so that operators can confirm the external constraint was received and understood.

Dependencies¶

Heartbeat Flow and Liveness Visibility
Operating Envelope Updates Legacy Circuit Capacity for Managed Scope and Legacy UI

Acceptance Criteria¶

UpdateGroupCapacityForecast from a Vector-compatible mock Capacity Provider resolves the bound group_id to exactly one managed microgrid scope and records inbound audit on the OSCP connection detail.
The OSCP domain translates the forecast into the protocol-agnostic microgrid OperatingEnvelope boundary rather than passing OSCP-specific fields into microgrid.
The OSCP operations UI shows the last received forecast and whether the latest intake outcome was accepted or rejected.
Unknown, disabled, or ambiguous bindings return deterministic protocol outcomes and visible failure audit in the OSCP operations view.

OSCP Fallback Mode Activation and Visibility¶

Linear issue: COR-57

User Story¶

As a support operator, I want OSCP offline or degraded forecast conditions to move BetterFleet into a visible fallback mode so that the site remains constrained safely without appearing to be in a red-alarm fail-safe state.

Dependencies¶

Heartbeat Flow and Liveness Visibility
Forecast Intake to Microgrid Constraint and UI Effect
Operating Envelope Updates Legacy Circuit Capacity for Managed Scope and Legacy UI

Acceptance Criteria¶

When OSCP heartbeat timeout or equivalent offline detection occurs and valid fallback forecast coverage exists for now, BetterFleet activates fallback-derived constraints for the mapped managed scope.
While fallback-derived constraints are active, operator surfaces show a distinct yellow fallback mode rather than a red fail-safe alarm.
Entering fallback mode creates notification and incident context correlated to the affected connection and managed scope.
When normal online state and valid non-fallback forecast coverage are restored, BetterFleet exits fallback mode deterministically and records that recovery for operator visibility and audit.

Forecast Gap Policy Configuration and Visibility¶

Linear issue: COR-58

User Story¶

As an integration engineer or operator, I want BetterFleet to apply a configured and visible policy when an OSCP forecast has gaps so that uncovered time periods are handled deterministically and safely.

Dependencies¶

Forecast Intake to Microgrid Constraint and UI Effect
Operating Envelope Updates Legacy Circuit Capacity for Managed Scope and Legacy UI
OSCP Fallback Mode Activation and Visibility

Acceptance Criteria¶

If a healthy primary forecast has no active primary block for now but a matching fallback block exists, BetterFleet applies the fallback block and enters yellow fallback mode.
If no matching fallback block exists for now, BetterFleet applies the configured gap policy and enters yellow fallback mode with notification and incident context.
Manage UI exposes the gap-policy configuration surface for the OSCP connection profile.
The current delivered selectable option set contains only the least-risk safe-default or non-OSCP path; future options such as dead reckoning are visible as future extension space but not selectable in this delivery slice.
Operator-visible state distinguishes normal forecast operation from gap-driven fallback operation without using a red fail-safe alarm.

Auditable OSCP Outcomes¶

Linear issue: COR-47

User Story¶

As a support operator, I want important OSCP outcomes to be durably auditable so that I can diagnose accepted and rejected protocol behaviour without relying on transient HTTP responses or logs.

Dependencies¶

Forecast Intake to Microgrid Constraint and UI Effect
Registration Flow and Status Visibility
Handshake Flow and Negotiated Behaviour Visibility
Heartbeat Flow and Liveness Visibility
Intentional OSCP Disconnect Returns Control to Operator
OSCP Fallback Mode Activation and Visibility
Forecast Gap Policy Configuration and Visibility

Acceptance Criteria¶

Accepted OSCP forecasts create durable event-store audit that identifies the connection, binding, and translation outcome.
Rejected OSCP forecasts create durable event-store audit that identifies the attempted connection or binding context and the rejection reason.
Material OSCP connection lifecycle failures and recoveries create durable audit records rather than relying only on mutable latest-state fields.
Fallback-mode entered, fallback-mode exited, gap-policy applied, and intentional disconnect handover outcomes create durable audit records with enough context for operator diagnosis.
OSCP operations UI or read models surface the latest auditable outcome from event-backed projection state rather than requiring support users to inspect raw logs.

Operating Envelope Charting and View Dependency¶

Linear issue: COR-48

User Story¶

As a Vector delivery stakeholder, I want the milestone to explicitly track dependency on generic operating-envelope visibility so that OSCP forecast work does not silently own a microgrid feature while still depending on it for demonstrable operator outcomes.

Dependencies¶

Canonical Scoped Operating Envelope View and History (docs/work/backlog/microgrid/stories.md)
Operating Envelope Updates Legacy Circuit Capacity for Managed Scope and Legacy UI

Implementation Note¶

Canonical feature ownership remains with the existing microgrid story Canonical Scoped Operating Envelope View and History; this COR story exists only to track the Vector dependency and integration expectation.

Acceptance Criteria¶

The Vector story set explicitly references the existing microgrid operating-envelope story as the upstream owner of generic operating-envelope history and charting or view capability.
The Vector milestone has a dedicated story for the dependency so the moved charting or view work is visible without being redefined as OSCP-owned scope.
The dependency story makes clear how the generic operating-envelope visibility work relates to the interim legacy circuit effect owned by COR-19.

Group Measurement Publication via Dispatcher¶

Linear issue: COR-21

User Story¶

As a support operator, I want periodic group measurements to be published back to the Capacity Provider so that outbound metering is visible and auditable in the UI.

Dependencies¶

Heartbeat Flow and Liveness Visibility

Acceptance Criteria¶

For a connection profile with measurement_publication_mode=GROUP, the measurement job creates due outbound publications at measurement_publication_interval_seconds.
The interim dispatcher sends UpdateGroupMeasurements to a Vector-compatible mock Capacity Provider and records success or failure.
OSCP operations UI shows last group measurement publication time, delivery state, and linked connection and binding identifiers.
Published measurements are sourced from microgrid-facing aggregated read models rather than OSCP-specific duplicated state.
If the profile is configured for INTERMITTENT, the visible publication history shows that each group measurement represents one closed measurement window rather than an ever-increasing cumulative series.

Vector Asset Measurement Profile¶

Linear issue: COR-22

User Story¶

As an integration engineer, I want a Vector-targeted connection profile to send asset-shaped measurement publications so that partner-specific metering expectations can be met without changing the core OSCP model.

Dependencies¶

Group Measurement Publication via Dispatcher

Acceptance Criteria¶

A Vector-targeted connection configured with measurement_publication_mode=ASSET requires a reporting asset identity and measurement_configuration=INTERMITTENT before outbound publication is allowed.
The measurement job creates one due outbound publication every 15 minutes aligned to the clock hour for the configured bound group_id.
The measurement job and dispatcher send UpdateAssetMeasurements to a Vector-compatible mock Capacity Provider using the configured reporting asset identity and bound group_id.
The published asset payload contains energy totals for the closed 15-minute window and instantaneous maximum load for that same window.
The published energy measurement includes the required initial_measure_time for the measurement window when INTERMITTENT mode is active.
OSCP operations UI shows that the connection is running in ASSET measurement mode and displays the last asset-measurement publication result.
Switching between GROUP and ASSET publication mode changes only the OSCP serialization path and does not change microgrid-facing contracts.

Manual Adjustment Request from UI¶

Linear issue: COR-23

User Story¶

As an operator, I want to request a capacity adjustment from the Capacity Provider from the OSCP UI so that outbound adjustment flow can be demonstrated and audited end-to-end.

Dependencies¶

Forecast Intake to Microgrid Constraint and UI Effect

Acceptance Criteria¶

OSCP connection detail UI provides a manual adjustment action when an active forecast exists for the binding.
Submitting the action persists an outbound AdjustGroupCapacityForecast publication and the dispatcher sends it to a Vector-compatible mock Capacity Provider.
The UI shows the outbound request state, timestamp, and correlation to the forecast that prompted the request.
The action is blocked with deterministic UI feedback when no active forecast or valid binding exists.

Compliance Error from Simulated Microgrid Breach¶

Linear issue: COR-24

User Story¶

As a support operator, I want a microgrid inability-to-comply condition to raise an OSCP compliance error so that protocol non-compliance can be demonstrated from site behavior through to outbound publication.

Dependencies¶

Forecast Intake to Microgrid Constraint and UI Effect
Microgrid Status Summary View
Manage UI Cycle and Breach Visibility

Acceptance Criteria¶

A simulated breach or non-compliance condition from bf-depot-sim or the microgrid status path against an active OSCP forecast creates a GroupCapacityComplianceError outbound publication.
The interim dispatcher sends the compliance error to a Vector-compatible mock Capacity Provider and records its correlation to the triggering forecast.
The OSCP operations UI shows the linked microgrid breach context and the resulting compliance publication on the connection detail.
Repeated detection of the same breach condition does not create uncontrolled duplicate compliance publications.

Intentional OSCP Disconnect Returns Control to Operator¶

Linear issue: COR-54

User Story¶

As an operator, I want intentionally disconnecting an OSCP connection to immediately clear active OSCP constraints and return control to the current non-OSCP path so that I can knowingly take back full local control.

Dependencies¶

OSCP Binding and Connection Profile Management
Forecast Intake to Microgrid Constraint and UI Effect
OSCP Fallback Mode Activation and Visibility

Acceptance Criteria¶

Manage UI warns the user that disconnecting the OSCP connection will immediately clear active OSCP forecast and fallback constraints and return the managed scope to the current non-OSCP path.
Confirming the disconnect immediately withdraws active OSCP-derived envelopes for the managed scope rather than waiting for natural expiry.
After disconnect, operator surfaces clearly show that OSCP control has ended and full local or non-OSCP control has resumed.
If disconnect occurs while fallback mode is active, fallback mode exits deterministically as part of the disconnect handover.
The disconnect action and resulting control handover are auditable with connection and managed-scope context.

Surface Connection Errors in UI¶

Linear issue: COR-34

User Story¶

As a support operator, I want the latest OSCP connection error to be visible in OSCP management so that I can understand the current failure state without inspecting backend logs.

Dependencies¶

Handshake Flow and Negotiated Behaviour Visibility
Heartbeat Flow and Liveness Visibility

Acceptance Criteria¶

OSCP management surfaces the latest tracked connection error for each configuration when a connection or lifecycle failure has occurred.
Deterministic no-error and cleared-error states are visible so operators can tell when no tracked error currently applies.
A failed lifecycle attempt such as timeout, offline transition, or equivalent tracked failure leaves enough visible error context for support diagnosis.

Secure Single OSCP Route and Role Permissions¶

Linear issue: COR-45

User Story¶

As a system administrator or manager, I want OSCP protocol endpoints exposed through one authenticated route with explicit role permissions so that unsupported aliases and unauthorised access are removed.

Dependencies¶

Handshake Flow and Negotiated Behaviour Visibility
Heartbeat Flow and Liveness Visibility

Acceptance Criteria¶

The existing OSCP router is mounted only once at /oscp....
The /api/oscp... alias is removed so there is no duplicate OSCP route exposure.
Access to OSCP protocol endpoints requires the intended authenticated path and does not rely on the previous bypass behaviour.
At minimum, users with Manager and System Admin roles are permitted to use the intended authenticated OSCP endpoint path.
Users without the required OSCP permissions are blocked deterministically from using the OSCP protocol endpoints.
User-facing endpoint guidance reflects the retained /oscp... route shape and the expected authentication behaviour.

Depot Sim OSCP Capacity Provider Simulator¶

Linear issue: COR-49

User Story¶

As a QA or integration engineer, I want bf-depot-sim to act as a sustainable OSCP Capacity Provider simulator so that end-to-end Vector OSCP testing no longer depends on the temporary single-file simulator.

Dependencies¶

Handshake Flow and Negotiated Behaviour Visibility
Heartbeat Flow and Liveness Visibility
Forecast Intake to Microgrid Constraint and UI Effect
Group Measurement Publication via Dispatcher
Vector Asset Measurement Profile
Compliance Error from Simulated Microgrid Breach
Manual Adjustment Request from UI
Intentional OSCP Disconnect Returns Control to Operator
OSCP Fallback Mode Activation and Visibility
Forecast Gap Policy Configuration and Visibility

Implementation Note¶

This story replaces bf-manage-core/scripts/oscp_cp_client.py as the primary testing surface for current OSCP validation.

Acceptance Criteria¶

bf-depot-sim can receive and respond to BetterFleet handshake requests as a Capacity Provider simulator.
bf-depot-sim can send handshake acknowledgements to BetterFleet in the current lifecycle flow.
bf-depot-sim can send and receive heartbeats in support of current lifecycle testing.
bf-depot-sim can send OSCP forecasts to BetterFleet and vary those forecasts in controlled scenarios.
bf-depot-sim can send forecast sets that include primary coverage, fallback coverage, and deliberate forecast gaps for deterministic fallback-mode testing.
bf-depot-sim can receive and validate outbound BetterFleet OSCP messages that are currently in scope, including compliance errors, measurement publications, and manual adjustment requests.
bf-depot-sim can surface or retain enough simulator-side state to confirm whether outbound BetterFleet OSCP messages were received, accepted, rejected, or intentionally ignored in a test scenario.
The simulator can reproduce BetterFleet-initiated and Capacity Provider-initiated handshake timeout scenarios described in docs/reference/system-design/oscp/sim-requirements.md.
The simulator can reproduce heartbeat or offline failure scenarios from docs/reference/system-design/oscp/sim-requirements.md, including cases where one side stops sending or accepting heartbeats.
The simulator plus BetterFleet OSCP operations flow can validate fallback-mode entry, restored-normal exit, forecast-gap scenarios, and intentional-disconnect handover without relying on the temporary single-file simulator.
The simulator provides manual state editing or scenario control that can force mismatch or error cases which should produce deterministic 403 or offline outcomes during end-to-end testing.