refactor(architecture): add typed controller command and snapshot contracts by stritti · Pull Request #214 · smart-swimmingpool/pool-controller

stritti · 2026-10-04T16:05:49Z

Summary

Introduces the fixed-size, allocation-free controller command and immutable snapshot contracts needed for the architecture migration discussed in #170, without changing production behavior yet.

Contract surface

typed OperationMode with stable auto / manu / boost / timer wire values
fixed-size, trivially-copyable ControllerCommand covering existing runtime controller mutations
independent timer-start and timer-end commands so partial MQTT/Web updates remain lossless
bounded SET_NTP_SERVER plus ControllerSettingsSnapshot::ntpServer using a shared 127-byte-plus-NUL value with rejection instead of truncation
relative pool/solar pump toggles with explicit Web/NORVI/Olimex mode policy
relative CYCLE_MODE, evaluated by the owner against current state rather than an adapter snapshot
coherent SensorSnapshot with generation/timestamp, mapping identity and a deduplicated 20-device detected inventory with independent reading validity
SystemSnapshot projections for timer runtime, temperature-circulation settings, runtime settings and GREEN/YELLOW/RED time degradation
allocation-free local IPv4 projection (4 x uint8_t + valid) in NetworkSnapshot
both free heap and maximum allocatable heap diagnostics in SystemSnapshot
native contract tests plus OpenSpec requirements/design/tasks for ownership and migration gates

Scope boundary

The general controller command queue owns runtime controller/domain settings that must obey the Core-1 single-writer rule. WiFi/MQTT credentials and authentication secrets remain in dedicated provisioning/auth services.

NTP server text is a runtime controller setting, so validation/persistence belongs to Core 1. NTP client/network lifecycle remains owned by the time service. Local IP and heap values are read-only snapshot projections; outbound adapters format/use those copies rather than querying NetworkManager, WiFi or ESP after adoption.

Architectural constraints

no dynamic allocation in the contracts
no Arduino/protocol/hardware dependencies in the value types
mutable controller state remains single-writer on Core 1
OneWire/Dallas remains sensor-owner state after feat: multicore task architecture #170
external compatibility is unchanged, including historic manu
contracts remain compatible with the firmware C++ toolchain
native GCC ABI: ControllerCommand 156 bytes, SensorSnapshot 376 bytes, SystemSnapshot 596 bytes; transport PRs must verify queue/store and critical-section budgets

Follow-up dependency graph

Minimal robust graph:

#214 -> {#216, #217}
{#216, #217, #170 sensor ownership} -> #218 for the sensor-dependent adapter migration
#218 -> #219
{#214, #170} -> #220, independently of refactor(domain): make control rules return decisions instead of driving relays #219
{#218, #219, #220} -> #221

#216 and #217 are currently stacked on an older #214 contract and must be synchronized with this completed surface. #218 already contains the current #216 and #217 heads as ancestors, so it should be restacked after those foundation PRs rather than reintroducing queue/store implementations.

For #218 sensor reads, first project the sensor owner's cached acquisition/discovery generation. If that bridge is not used, #220 becomes a hard predecessor of the sensor-read part of #218. #170 remains the ownership gate before any cross-task Dallas adoption.

A conservative serial merge order is therefore #214, #216, #217, #218, #219, #220, #221, with #216/#217 swappable and #220 movable earlier once #170 + #214 are satisfied.

Detailed merge gates, NTP legacy-value handling, resource budgets and regression scenarios are in openspec/changes/controller-architecture-contracts/design.md and the contract specification.

Validation

Current head: f5994e78c2bb25020bfa5e7e40114bf2cec40471.

Native Tests: success, 120 suites / 581 assertions, 0 failures
Relay Safety: success, 27 checks, 0 failures
PlatformIO: success for esp32dev, norvi_ae01_r and olimex_esp32_c6_evb
MegaLinter: success
CodeQL: success
all non-outdated review findings through 2026-10-05 are addressed and all review threads are resolved
SystemSnapshot retains a compile-time 600-byte budget guard and is 596 bytes on the native GCC ABI

Related to #170.

github-actions · 2026-10-04T16:06:25Z

✅⚠️MegaLinter analysis: Success with warnings

Descriptor	Linter	Files	Errors	Elapsed time
✅ ACTION	actionlint	8	0	0.63s
✅ BASH	bash-exec	2	0	0.51s
✅ BASH	shellcheck	2	0	0.54s
✅ BASH	shfmt	2	0	0.01s
✅ C	clang-format	1	0	0.04s
✅ C	cppcheck	1	0	0.02s
✅ C	cpplint	1	0	0.28s
✅ CPP	clang-format	90	0	0.62s
✅ CPP	cppcheck	90	0	5.56s
✅ CPP	cpplint	90	0	6.81s
✅ EDITORCONFIG	editorconfig-checker	275	0	0.6s
✅ JSON	jsonlint	6	0	0.12s
✅ JSON	v8r	6	0	4.33s
⚠️ MARKDOWN	markdownlint	107	4	4.1s
✅ YAML	yamllint	26	0	1.11s

Detailed Issues

⚠️ MARKDOWN / markdownlint - 4 errors

.opencode/skills/web-ui/SKILL.md:34 error MD028/no-blanks-blockquote Blank line inside blockquote
docs/superpowers/plans/2026-08-10-olimex-c6-local-ui-implementation.md:106:401 error MD013/line-length Line length [Expected: 400; Actual: 452]
docs/superpowers/plans/2026-08-16-norvi-button-calibration.md:7:401 error MD013/line-length Line length [Expected: 400; Actual: 412]
openspec/changes/controller-architecture-contracts/design.md:171:401 error MD013/line-length Line length [Expected: 400; Actual: 448]

Notices

⚠️ Your configuration references items that have been removed from MegaLinter and are ignored: MAKEFILE, MAKEFILE_CHECKMAKE, MARKDOWN_MARKDOWN_LINK_CHECK. See Removed linters to find their replacements.

See detailed reports in MegaLinter artifacts

Your project could benefit from a custom flavor, which would allow you to run only the linters you need, and thus improve runtime performances. (Skip this info by defining FLAVOR_SUGGESTIONS: false)

Documentation: Custom Flavors
Command: npx mega-linter-runner@10.1.0 --custom-flavor-setup --custom-flavor-linters ACTION_ACTIONLINT,BASH_EXEC,BASH_SHELLCHECK,BASH_SHFMT,C_CPPCHECK,C_CPPLINT,C_CLANG_FORMAT,CPP_CPPCHECK,CPP_CPPLINT,CPP_CLANG_FORMAT,EDITORCONFIG_EDITORCONFIG_CHECKER,JSON_JSONLINT,JSON_V8R,MARKDOWN_MARKDOWNLINT,YAML_YAMLLINT

Show us your support by starring ⭐ the repository

github-actions · 2026-10-04T16:07:02Z

Native Test Coverage

Metric	Value
Line Coverage	48.2%
Branch Coverage	74.8%
Lines Hit/Total	392/814
Branches Hit/Total	178/238

Report from native unit tests (ASan + gcov).

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: d81eeaa3ec

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

chatgpt-codex-connector · 2026-10-04T16:20:22Z

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.

chatgpt-codex-connector · 2026-10-04T16:20:42Z

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.

chatgpt-codex-connector · 2026-10-04T16:20:50Z

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.

github-actions · 2026-10-04T16:21:25Z

Native Test Coverage

Metric	Value
Line Coverage	48.2%
Branch Coverage	74.8%
Lines Hit/Total	392/814
Branches Hit/Total	178/238

Report from native unit tests (ASan + gcov).

github-actions · 2026-10-04T16:22:44Z

Native Test Coverage

Metric	Value
Line Coverage	48.2%
Branch Coverage	74.8%
Lines Hit/Total	392/814
Branches Hit/Total	178/238

Report from native unit tests (ASan + gcov).

github-actions · 2026-10-05T12:41:16Z

Native Test Coverage

Metric	Value
Line Coverage	48.6%
Branch Coverage	76.0%
Lines Hit/Total	399/821
Branches Hit/Total	190/250

Report from native unit tests (ASan + gcov).

chatgpt-codex-connector · 2026-10-05T12:42:06Z

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.

github-actions · 2026-10-05T12:42:35Z

Native Test Coverage

Metric	Value
Line Coverage	48.6%
Branch Coverage	76.0%
Lines Hit/Total	399/821
Branches Hit/Total	190/250

Report from native unit tests (ASan + gcov).

chatgpt-codex-connector · 2026-10-05T12:43:19Z

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.

github-actions · 2026-10-05T12:43:48Z

Native Test Coverage

Metric	Value
Line Coverage	48.6%
Branch Coverage	76.0%
Lines Hit/Total	399/821
Branches Hit/Total	190/250

Report from native unit tests (ASan + gcov).

github-actions · 2026-10-05T12:45:08Z

Native Test Coverage

Metric	Value
Line Coverage	48.6%
Branch Coverage	76.0%
Lines Hit/Total	399/821
Branches Hit/Total	190/250

Report from native unit tests (ASan + gcov).

chatgpt-codex-connector · 2026-10-05T12:48:05Z

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.

chatgpt-codex-connector · 2026-10-05T12:48:09Z

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.

github-actions · 2026-10-05T12:49:09Z

Native Test Coverage

Metric	Value
Line Coverage	48.6%
Branch Coverage	76.0%
Lines Hit/Total	399/821
Branches Hit/Total	190/250

Report from native unit tests (ASan + gcov).

github-actions · 2026-10-05T12:50:15Z

Native Test Coverage

Metric	Value
Line Coverage	48.6%
Branch Coverage	76.0%
Lines Hit/Total	399/821
Branches Hit/Total	190/250

Report from native unit tests (ASan + gcov).

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 52b88a8c94

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Co-authored-by: stritti <stritti@users.noreply.github.com>

chatgpt-codex-connector · 2026-10-05T20:10:57Z

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.

Co-authored-by: stritti <stritti@users.noreply.github.com>

chatgpt-codex-connector · 2026-10-05T20:15:56Z

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.

github-actions · 2026-10-05T20:22:28Z

Native Test Coverage

Metric	Value
Line Coverage	49.3%
Branch Coverage	76.4%
Lines Hit/Total	411/833
Branches Hit/Total	194/254

Report from native unit tests (ASan + gcov).

Co-authored-by: stritti <stritti@users.noreply.github.com>

chatgpt-codex-connector · 2026-10-05T20:31:43Z

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.

github-actions · 2026-10-05T20:33:10Z

Native Test Coverage

Metric	Value
Line Coverage	49.3%
Branch Coverage	76.4%
Lines Hit/Total	411/833
Branches Hit/Total	194/254

Report from native unit tests (ASan + gcov).

Co-authored-by: stritti <stritti@users.noreply.github.com>

chatgpt-codex-connector · 2026-10-10T20:28:01Z

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.

github-actions · 2026-10-10T20:28:55Z

Native Test Coverage

Metric	Value
Line Coverage	49.3%
Branch Coverage	76.4%
Lines Hit/Total	411/833
Branches Hit/Total	194/254

Report from native unit tests (ASan + gcov).

stritti added 10 commits October 4, 2026 18:02

refactor: add typed operation mode contract

933e62a

refactor: add fixed-size controller command contract

29d24a6

refactor: add controller read-model snapshots

ac9300b

test: cover controller architecture contracts

4d7ecf8

test: register controller contract suite

0c1e71d

test: run controller contract suite

1211182

docs: initialize controller architecture OpenSpec change

da5aae4

docs: propose controller architecture contracts

2d29550

docs: design controller architecture contracts

7102da5

docs: track controller architecture contract tasks

d81eeaa

stritti mentioned this pull request Oct 4, 2026

refactor(domain): store operation mode as typed enum #215

Merged

chatgpt-codex-connector Bot reviewed Oct 4, 2026

View reviewed changes

Comment thread src/ControllerCommand.hpp Outdated

Comment thread src/ControllerSnapshot.hpp

style: satisfy clang-format for operation mode

bca65d5

style: satisfy cpplint assertions

edea128

docs: wrap architecture proposal line

600534c

stritti added 3 commits October 4, 2026 22:02

fix(architecture): keep operation mode contract firmware compatible

60be70c

fix(architecture): cover circulation settings in command contract

b9e0428

fix(architecture): project timer and circulation state in snapshots

bdc280a

stritti added 3 commits October 5, 2026 14:41

test(native): run snapshot diagnostics contract test

0d72843

docs(openspec): require snapshot-owned adapter diagnostics

6871c03

docs(openspec): track complete diagnostics projection

52b88a8

docs(openspec): complete adapter read-model design

f718feb

stritti added 2 commits October 5, 2026 14:47

style(native): preserve clang-format alignment

bedaca5

style(native): satisfy snapshot diagnostics lint

f5994e7

chatgpt-codex-connector Bot reviewed Oct 5, 2026

View reviewed changes

fix(contracts): reject noncanonical raw NTP values in valid()

71b01f3

Co-authored-by: stritti <stritti@users.noreply.github.com>

stritti mentioned this pull request Oct 5, 2026

contract: extend read model before adapter migration (epoch, min-heap, SSID, batch, audit sources) #222

Open

docs(openspec): track deferred contract extensions in #222

0789af8

Co-authored-by: stritti <stritti@users.noreply.github.com>

ci: retrigger norvi builds after hosted-runner acquisition failure

e06ae8b

Co-authored-by: stritti <stritti@users.noreply.github.com>

chore: retrigger CI checks

0f4005b

Co-authored-by: stritti <stritti@users.noreply.github.com>

stritti merged commit a6a2734 into main Oct 10, 2026
11 checks passed

Conversation

stritti commented Oct 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Contract surface

Scope boundary

Architectural constraints

Follow-up dependency graph

Validation

Uh oh!

github-actions Bot commented Oct 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅⚠️MegaLinter analysis: Success with warnings

Detailed Issues

Notices

Uh oh!

github-actions Bot commented Oct 4, 2026

Native Test Coverage

Uh oh!

chatgpt-codex-connector Bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

Uh oh!

Uh oh!

chatgpt-codex-connector Bot commented Oct 4, 2026

Uh oh!

chatgpt-codex-connector Bot commented Oct 4, 2026

Uh oh!

chatgpt-codex-connector Bot commented Oct 4, 2026

Uh oh!

github-actions Bot commented Oct 4, 2026

Native Test Coverage

Uh oh!

github-actions Bot commented Oct 4, 2026

Native Test Coverage

Uh oh!

github-actions Bot commented Oct 5, 2026

Native Test Coverage

Uh oh!

chatgpt-codex-connector Bot commented Oct 5, 2026

Uh oh!

github-actions Bot commented Oct 5, 2026

Native Test Coverage

Uh oh!

chatgpt-codex-connector Bot commented Oct 5, 2026

Uh oh!

github-actions Bot commented Oct 5, 2026

Native Test Coverage

Uh oh!

github-actions Bot commented Oct 5, 2026

Native Test Coverage

Uh oh!

chatgpt-codex-connector Bot commented Oct 5, 2026

Uh oh!

chatgpt-codex-connector Bot commented Oct 5, 2026

Uh oh!

github-actions Bot commented Oct 5, 2026

Native Test Coverage

Uh oh!

github-actions Bot commented Oct 5, 2026

Native Test Coverage

Uh oh!

chatgpt-codex-connector Bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

chatgpt-codex-connector Bot commented Oct 5, 2026

Uh oh!

chatgpt-codex-connector Bot commented Oct 5, 2026

Uh oh!

github-actions Bot commented Oct 5, 2026

Native Test Coverage

stritti commented Oct 4, 2026 •

edited

Loading

github-actions Bot commented Oct 4, 2026 •

edited

Loading