Skip to content

refactor(drivercontrol): move operator holds out of the API - #1997

Merged
frahlg merged 1 commit into
srcfl:masterfrom
hannesb90:refactor/driver-control-holds
Nov 15, 2026
Merged

frahlg merged 1 commit into
srcfl:masterfrom
hannesb90:refactor/driver-control-holds

Conversation

@hannesb90

Copy link
Copy Markdown
Contributor

Problem and result

Step 2 of the proposal in #1994 (ADR 0012), toward #520. Stacked on #1995;
only the last commit is new here.

The operator hold (one bounded value per driver, sent and released under one
per-driver lock, handed back to the driver's own default when it ends) lived
inside internal/api. A planned value will need the same lock and the same
expiry, or an operator hold and a planned one would each expire into a default
that undoes the other. This moves that code, unchanged, into
internal/drivercontrol, and does nothing else with it yet.

  • drivercontrol.Holds owns the per-driver state, Send, ArmLocked,
    Expire, SendDefault, Active, Peek and Clear. The bodies are the
    former Server methods, with the server's registry passed in as a small
    interface.
  • The API keeps its routes, status codes, response bodies and
    Server.SendDriverDefault (used by the watchdog in cmd/ftw). The registry
    lifecycle hook now calls Holds.Clear.
  • The send error is still answered while the per-driver lock is held, as
    before. Send takes a done callback for that reason, so the status read
    that explains a 404 or 409 cannot race a lifecycle change.
  • As the owner asked in answer 3 on docs(adr): propose heat control from a target temperature and a learned twin #1994, the unused thermal policy draft
    is removed: DecideIntent, DecisionInput, Intent, IntentKind,
    TemperatureBand, MarginalPrice and the synthetic_price strategy.
    Nothing outside the package used them. The declaration vocabulary that feat(drivers): let a control declare what it does to heat #1995
    uses (AssetKind, InfluenceStrategy, ValidAssetKind) stays.

Scope and safety

No behaviour change is intended, and none is visible to a user.

Verification

Run on a Raspberry Pi 4 (linux/arm64), Go 1.26.10:

go vet ./internal/drivercontrol ./internal/thermal ./internal/drivers ./internal/api ./cmd/ftw   clean
go test ./internal/drivercontrol ./internal/thermal ./internal/drivers -count=1                  ok
go test ./internal/api -count=1                                                                    ok
go test ./cmd/ftw -count=1   (umask 022)                                                           ok

With the Pi's default umask 002, seven cmd/ftw nova key tests fail because
the temporary key directory is group-writable. That is the environment, and
the same on master. The race detector does not run on this Pi's 39-bit VMA;
CI covers it.

Checklist

  • The change follows VISION.md and one selected scope.
  • I checked overlapping PRs and coordinated shared files/contracts.
  • Relevant checks cover the changed behaviour and failure paths.
  • A human reviewed changed UI in a browser, or no UI changed.
  • A Changeset is included, or the change is exempt.
  • Every commit has a DCO sign-off.

🤖 Generated with Claude Code

@frahlg frahlg left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ready to merge in content; it needs one rebase first. #1995 is merged (squashed as 1e525ac), and this branch still carries #1995's earlier commits, so it now conflicts with master in five files (api/api_driver_control.go, api/api_driver_thermal_test.go, api/api_drivers_debug.go, drivers/catalog_thermal.go, thermal/model.go). Please rebase onto master, dropping #1995's commits, and I will merge it.

Reviewed and tested: behaviour-neutral. Compared line by line with the old api_driver_control.go: same lock order, generation and identity checks, non-blocking SendDefault from the tick, 10 s deadlines, routes, 24 h cap, 4 h default and hold JSON. The existing hold-race tests pass unchanged apart from the call target, and the full make verify passes with the stack on today's master. Removing DecideIntent and the rest of the unused thermal code follows decision 3.

Low notes for the next step:

  • The test seams are part of the production API (beforeStateLock, beforeDefaultStateLock, exported State.Lock/Unlock). A future planned-value caller could hold the per-driver lock through them; an export_test.go would keep them test-only.
  • Holds.State(name) creates an entry for any name; keep it unexported.
  • Active takes the per-driver lock. When #2013's dispatcher calls it from the control tick, make sure it never waits behind an operator send (as SendDefault does with TryLock).

The per-driver lock, hold, expiry and default path move unchanged from
internal/api into internal/drivercontrol, so a planned value can later go
through the same lock and expiry as an operator's (ADR 0012). The API
keeps its routes, responses and SendDriverDefault; the registry lifecycle
hook now clears holds through the package.

As asked on srcfl#1994, the unused thermal policy draft goes with it:
DecideIntent, DecisionInput, Intent, TemperatureBand, MarginalPrice and
the synthetic_price strategy. The declaration vocabulary stays.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Signed-off-by: hannesb90 <[email protected]>
@hannesb90
hannesb90 force-pushed the refactor/driver-control-holds branch from aef7ff1 to b10ae8c Compare November 15, 2026 07:04
hannesb90 added a commit to hannesb90/forty-two-watts that referenced this pull request Nov 15, 2026
The low notes from the review of srcfl#1997, for the step that adds a
planned-value caller:

- The test seams were part of the production API: two hook parameters on
  Send and SendDefault, and exported State.Lock, State.Unlock, ArmLocked,
  Expire, Peek, Len and State.CurrentHold. A planned-value caller could
  have held the per-driver lock through them. They are now behind
  Holds.Seams, which panics outside a test binary. An export_test.go
  would not do: the API package's hold-race tests need them too.
- Holds.State, which created an entry for any name, is reachable only
  through Seams.
- Active takes the per-driver lock and so waits for a command in flight.
  TryActive is the same read for the control tick: it never waits, and
  says so when a command or a default holds the lock.

The hold-race tests are unchanged apart from the call target.

Co-Authored-By: Claude Fable 5.2 <[email protected]>
Signed-off-by: hannesb90 <[email protected]>

@frahlg frahlg left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for the rebase. At b10ae8c it is one commit and nothing from #1995 was lost: every line that leaves the API lands in drivercontrol, and the thermal removals follow decision 3. Lock order, generation and identity checks, TryLock in SendDefault, the 10 s deadlines, routes, caps and hold JSON are unchanged. Merged with today's master (#1996, #2009 and #2010 included), go build ./... and go vet are clean. go test passes for api, drivercontrol, thermal and cmd/ftw, and -race passes for the first three.

Notes for #2013, not blocking:

  • Active takes the per-driver lock. Called from the control tick, it could wait up to 10 s behind an operator send, so use TryLock there as SendDefault does.
  • The test seams (State.Lock/Unlock, ArmLocked, Peek and the like) are still exported. Moving them to export_test.go would keep a future caller from taking the lock through them.

@frahlg
frahlg merged commit 9c6eda8 into srcfl:master Nov 15, 2026
21 checks passed
hannesb90 added a commit to hannesb90/forty-two-watts that referenced this pull request Nov 15, 2026
The low notes from the review of srcfl#1997, for the step that adds a
planned-value caller:

- The test seams were part of the production API: two hook parameters on
  Send and SendDefault, and exported State.Lock, State.Unlock, ArmLocked,
  Expire, Peek, Len and State.CurrentHold. A planned-value caller could
  have held the per-driver lock through them. They are now behind
  Holds.Seams, which panics outside a test binary. An export_test.go
  would not do: the API package's hold-race tests need them too.
- Holds.State, which created an entry for any name, is reachable only
  through Seams.
- Active takes the per-driver lock and so waits for a command in flight.
  TryActive is the same read for the control tick: it never waits, and
  says so when a command or a default holds the lock.

The hold-race tests are unchanged apart from the call target.

Co-Authored-By: Claude Fable 5.2 <[email protected]>
Signed-off-by: hannesb90 <[email protected]>
frahlg added a commit that referenced this pull request Nov 15, 2026
The low notes from the review of #1997, for the step that adds a
planned-value caller:

- The test seams were part of the production API: two hook parameters on
  Send and SendDefault, and exported State.Lock, State.Unlock, ArmLocked,
  Expire, Peek, Len and State.CurrentHold. A planned-value caller could
  have held the per-driver lock through them. They are now behind
  Holds.Seams, which panics outside a test binary. An export_test.go
  would not do: the API package's hold-race tests need them too.
- Holds.State, which created an entry for any name, is reachable only
  through Seams.
- Active takes the per-driver lock and so waits for a command in flight.
  TryActive is the same read for the control tick: it never waits, and
  says so when a command or a default holds the lock.

The hold-race tests are unchanged apart from the call target.

Signed-off-by: hannesb90 <[email protected]>
Co-authored-by: hannesb90 <[email protected]>
Co-authored-by: Claude Fable 5.2 <[email protected]>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants