Microgrid Backlog Stories¶
Context Summary¶
- This folder holds microgrid stories that are aligned to the microgrid system design but are not currently assigned to an active project or milestone.
- System design reference:
docs/reference/system-design/microgrid.md.
Canonical Scoped Operating Envelope View and History¶
User Story¶
As an operations user, I want active and historical operating-envelope data visible through canonical microgrid surfaces so that externally supplied constraints are understandable without relying only on legacy circuit values.
Dependencies¶
- Operating Envelope Updates Legacy Circuit Capacity for Managed Scope and Legacy UI
Acceptance Criteria¶
- The canonical microgrid read surface exposes the active operating envelope associated with a microgrid or a scoped subtree, including effective capacity, validity window, status, and target scope.
- Operators can inspect operating-envelope source metadata and history without reading raw OSCP payload logs.
- When the interim legacy circuit available-capacity path is still active, the canonical operating-envelope view remains consistent with the effective legacy circuit value being applied.
- Expired, withdrawn, and superseded operating envelopes remain auditable through the canonical microgrid view.
Scoped External Capability Binding and Status¶
User Story¶
As an operations user, I want external capability state to be bindable to a scoped part of a microgrid so that different controllers or control modes can be represented for different sections of one site.
Dependencies¶
- External Capability Status to Microgrid Card
- Read-Only Microgrid Topology View
Acceptance Criteria¶
- The canonical microgrid model supports binding an external capability status source to either the whole microgrid or a scoped subtree rooted at one node.
- The product can represent different external capability states for different scoped parts of the same microgrid without creating additional microgrid identities.
- UI status surfaces identify the target scope for any scoped external capability state rather than implying that all status is site-wide.
- Before a generic inbound idempotency mechanism exists, repeating the same scoped external event reference may append duplicate stored history temporarily, but it must not create a conflicting visible latest scoped status outcome for the same capability and scope.
Competing Capability Source Conflict Handling¶
User Story¶
As a support or configuration user, I want competing source-device bindings for the same microgrid capability to fail clearly so that one device cannot silently take over control ownership from another.
Dependencies¶
- External Capability Status to Microgrid Card
Acceptance Criteria¶
- Attempting to configure or accept a second active source device for the same
microgrid + capabilityreturns a deterministic conflict outcome rather than silently reassigning the active control point. - The conflict outcome identifies the microgrid, capability type, existing active source, and incoming conflicting source clearly enough for support or configuration users to diagnose the problem.
- The previously active source binding remains unchanged after the conflict outcome.
- The product exposes a deterministic remediation path for resolving the competing-source conflict.
Read-Only Microgrid Topology View¶
User Story¶
As an operations user, I want to open a dedicated Microgrid topology view so that I can inspect the canonical node tree and attached assets for a site beyond the MVP balancing summaries.
Dependencies¶
- Derived Hierarchical Microgrid Structure for Load Balancing
Acceptance Criteria¶
- Opening the Microgrid topology view for a valid site renders the canonical node tree and attached assets from one backend response.
- The view exposes microgrid identity, depot identity, topology version where applicable, and last-updated context for the currently displayed topology.
- Every displayed attached asset is rendered against a valid visible node in the same topology view.
- Opening the topology view for an unknown or unresolved microgrid shows a deterministic not-found state.
Editable Topology and Terminology Alignment¶
User Story¶
As an operations user, I want the Manage UI to show microgrid node topology and updated terminology so that I can eventually configure and inspect the model directly.
Dependencies¶
- Read-Only Microgrid Topology View
Acceptance Criteria¶
- Relevant UI surfaces show
Microgrid,Microgrid Node, andNode Limitterminology consistently. - The topology view renders node hierarchy and attached assets from the canonical topology response.
- Topology-editing entry points, when introduced, are presented using the new terminology rather than legacy circuit-centric naming.
- Legacy terminology does not appear in updated microgrid topology-management surfaces.
Invalid Topology Edit Rejection¶
User Story¶
As an operations user, I want invalid topology edits to be rejected in the topology editor so that unsafe electrical structures cannot be saved.
Dependencies¶
- Editable Topology and Terminology Alignment
Acceptance Criteria¶
- Saving a topology edit that introduces a cycle is rejected with a deterministic validation error visible to the operator.
- Saving a topology edit that leaves an orphan node is rejected with a deterministic validation error visible to the operator.
- A valid topology edit is accepted and the refreshed topology view reflects the new saved structure.
- After a failed save, the visible topology remains unchanged and no partial edit is shown as applied.
Conflicting Topology Edit Detection¶
User Story¶
As an operations user, I want conflicting topology edits to fail clearly in the UI so that concurrent updates do not overwrite each other silently.
Dependencies¶
- Invalid Topology Edit Rejection
Acceptance Criteria¶
- Saving a topology edit from the most recent topology version succeeds normally.
- Saving a stale topology edit from a second browser session or stale page state is rejected with a visible conflict outcome.
- The conflict outcome includes enough detail for the operator to understand that the topology has changed since it was loaded.
- After reloading the latest topology, the operator can resubmit the intended edit successfully.
Node and Aggregate Limit Management¶
User Story¶
As an operations user, I want to manage node and microgrid aggregate limits so that I can configure enforceable operating constraints directly rather than only deriving them from existing asset configuration.
Dependencies¶
- Read-Only Microgrid Topology View
Acceptance Criteria¶
- The operator can create and update both node-scoped and microgrid-aggregate limits through the product surface used for limit management.
- After save, the active policy set is visible for the selected microgrid with scope, target, and schedule context.
- Invalid limit inputs are rejected with deterministic validation feedback visible to the operator.
- Reloading the same microgrid shows the saved active limits exactly as applied.
Physical Rating Guardrail in Limit Editing¶
User Story¶
As an operations user, I want limit editing to enforce physical ratings so that configured caps cannot exceed the actual capability of the node.
Dependencies¶
- Node and Aggregate Limit Management
Acceptance Criteria¶
- Entering a node hard cap above the physical rating is rejected with deterministic validation feedback on save.
- Entering a node hard cap equal to or below the physical rating is accepted and visible after refresh.
- The validation feedback identifies the node and the limit field that caused the rejection.
- The visible policy value after a successful save matches the accepted cap exactly.
Scheduled Limit Visibility Through TOU Reuse¶
User Story¶
As an operator or legacy integration user, I want TOU-driven scheduled caps to be visible on the microgrid so that existing scheduling behavior remains demonstrable during migration.
Dependencies¶
- Node and Aggregate Limit Management
Acceptance Criteria¶
- When a mapped TOU schedule becomes active, the visible active limit for the affected node or microgrid reflects the scheduled cap.
- When no TOU schedule is active, the visible active limit falls back to the non-scheduled cap.
- A legacy TOU write through the existing circuit path is reflected in the canonical microgrid limit view.
- Ambiguous TOU-to-node mappings fail with deterministic error feedback to the caller and do not produce a hidden state change.
Telemetry Fallback Visibility Under Degradation¶
User Story¶
As a support operator, I want degraded telemetry to produce visible fallback-demand behavior so that safe enforcement under data loss can be demonstrated.
Dependencies¶
- Manage UI Cycle and Breach Visibility
Acceptance Criteria¶
- In a simulator or controlled degraded-telemetry scenario, fresh telemetry results in visible
source_mode=MEASUREDon cycle or breach details. - In a simulator or controlled degraded-telemetry scenario, missing or stale telemetry results in visible
source_mode=FALLBACK_DERIVED. - The operator can inspect which fallback inputs and thresholds were used for the visible outcome.
- If fallback requirements cannot be satisfied, the visible cycle result fails safe with a deterministic reason code.
Deterministic Reason Code Replays¶
User Story¶
As a support operator, I want repeated runs of the same scenario to show the same reason-code ordering so that diagnosis and alert handling are consistent.
Dependencies¶
- Manage UI Cycle and Breach Visibility
Acceptance Criteria¶
- Visible cycle results show reason codes ordered by the precedence defined in the specification.
- Visible breach results show one deterministic primary reason code.
- Re-running the same seeded or repeated-input scenario yields the same ordered reason-code list each time.
- The ordering remains stable even if internal processing order changes.
Depot Simulator Topology and Policy Model¶
User Story¶
As a QA or system test engineer, I want depot simulator profiles to represent microgrid nodes and limit policies so that system tests mirror the full microgrid domain behavior beyond the MVP derived-structure approach.
Dependencies¶
- Read-Only Microgrid Topology View
- Node and Aggregate Limit Management
Acceptance Criteria¶
- Simulator profile configuration supports node hierarchy with parent-child relationships.
- Simulator profile configuration supports attached assets linked to node identifiers.
- Simulator supports loading node and aggregate policy inputs used by test scenarios.
- Invalid simulator topology configuration is rejected before scenario start.
Depot Simulator Degraded Telemetry and Compatibility Scenarios¶
User Story¶
As a QA or system test engineer, I want simulator scenarios for telemetry degradation and legacy alias paths so that rollout risks are validated end-to-end.
Dependencies¶
- Depot Simulator Topology and Policy Model
- Telemetry Fallback Visibility Under Degradation
Acceptance Criteria¶
- Simulator can produce missing or stale telemetry patterns for targeted nodes.
- Simulator scenarios can trigger both canonical microgrid rebalance requests and legacy circuit alias requests.
- Scenario runs produce deterministic outputs for repeated seeded runs.
- Scenario artifacts include enough output data to verify fallback source mode and reason-code behavior.
Legacy Rebalance Path with Visible Microgrid Effect¶
User Story¶
As a legacy integration client, I want existing circuit rebalance calls to continue working and change visible microgrid state so that migration is non-breaking and demonstrable.
Dependencies¶
- Hierarchical Rebalance Across Grid and Charger Circuits
- Manage UI Cycle and Breach Visibility
Acceptance Criteria¶
POST /api/circuit/{circuit_id}/rebalance_loadresolves to onemicrogrid_idplus one canonical scope and triggers one microgrid cycle.- The legacy response returns mapped identifiers and the resulting cycle is visible in the canonical microgrid status surfaces.
- Unresolvable circuit aliases return
409withCIRCUIT_ALIAS_NOT_RESOLVABLE. - Alias-path usage is auditable for migration tracking.
Legacy TOU Path Reflected in Canonical Microgrid View¶
User Story¶
As a legacy integration client, I want existing circuit TOU endpoints to remain functional and update visible canonical microgrid limits so that policy migration can happen incrementally.
Dependencies¶
- Node and Aggregate Limit Management
- Scheduled Limit Visibility Through TOU Reuse
Acceptance Criteria¶
GET/POST /api/circuit/{circuit_id}/tou_limitscontinues to accept and return legacy contract shapes.- Legacy TOU writes update the mapped microgrid or node limit schedule behavior and the resulting active limit is visible through the canonical microgrid limit view.
- Unsupported legacy scope mappings return deterministic
422errors. - Legacy and canonical reads are consistent for the same mapped target.