feedback_machines 0.1.4 → 0.6.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: 69efd10b7aafaac8c4cc56a500cbd3c533e289e82009e0dbfc2062d2397fed28
4
- data.tar.gz: ebdce4115e533c09dc1aa076296f6c53fb1641a56366129044c4da343ef14fc0
3
+ metadata.gz: '09539164aff03323c31bb2c22e8a3d25276066a470ce2d9810232ad88ec03c66'
4
+ data.tar.gz: 805b4cc3c1c912aa37db71a04b13ac6ffb5f3994038880988ad1f1c14b2ea8d9
5
5
  SHA512:
6
- metadata.gz: b6f36a4bac1e6eab1ef62cc2c07cf1910ddeecb7202a73f54f8cd69fbef326b054811821ab5da12a261dc70b9d097f634a5f04a0f165080b97c542ea9947bff1
7
- data.tar.gz: 2f55dcb2a6c703142f7b2bb583baaf66b0b08da8b7fad7812ae7dd705266c3448a11111302becf6f47e6d4c99f5c4464abce922267883ee3e10b05772dccc18a
6
+ metadata.gz: 666f74e89e90bd36a28d493d0ac044a37aec9ec494cf3698214315327b45baece89f937afca3302ad1df9afee109d99dbc2c030898dcbd79e485ff869f51e68c
7
+ data.tar.gz: 45b5c2648599062cf60e0f7ffeca2d536d8e142584375bd7e7914e04a174c24d9230497e12c194dd6ea969eb64688ac7e04945ec534c887fe30bb97a652524ac
data/CHANGELOG.md CHANGED
@@ -1,5 +1,74 @@
1
1
  # Changelog
2
2
 
3
+ ## [0.6.1](https://github.com/seuros/feedback_machines/compare/feedback_machines/v0.6.0...feedback_machines/v0.6.1) (2026-11-16)
4
+
5
+
6
+ ### Bug Fixes
7
+
8
+ * fix wrapped classes at load so building a value runs no Ruby ([9bb4894](https://github.com/seuros/feedback_machines/commit/9bb4894c90331d9112dbb49a74f130eaa28c4eb3))
9
+
10
+ ## [0.6.0](https://github.com/seuros/feedback_machines/compare/feedback_machines/v0.5.1...feedback_machines/v0.6.0) (2026-11-16)
11
+
12
+
13
+ ### ⚠ BREAKING CHANGES
14
+
15
+ * add Pid/Hysteresis restored and seal both controllers
16
+
17
+ ### Features
18
+
19
+ * add Pid/Hysteresis restored and seal both controllers ([c5dc3b7](https://github.com/seuros/feedback_machines/commit/c5dc3b7d97857ccd596562f6364c6918cb63b173))
20
+
21
+ ## [0.5.1](https://github.com/seuros/feedback_machines/compare/feedback_machines/v0.5.0...feedback_machines/v0.5.1) (2026-11-14)
22
+
23
+
24
+ ### Bug Fixes
25
+
26
+ * **deps:** require matryona-machines >= 0.4 ([3ddc2cc](https://github.com/seuros/feedback_machines/commit/3ddc2cca66cf3c87e3181b7da7aab665221dc43b))
27
+
28
+ ## [0.5.0](https://github.com/seuros/feedback_machines/compare/feedback_machines/v0.4.0...feedback_machines/v0.5.0) (2026-11-14)
29
+
30
+
31
+ ### ⚠ BREAKING CHANGES
32
+
33
+ * read reals exactly through matryona-machines 0.3
34
+
35
+ ### Features
36
+
37
+ * read reals exactly through matryona-machines 0.3 ([21418cd](https://github.com/seuros/feedback_machines/commit/21418cdbfe6b897fe9de975ca9b8a157aed6b648))
38
+
39
+ ## [0.4.0](https://github.com/seuros/feedback_machines/compare/feedback_machines/v0.3.0...feedback_machines/v0.4.0) (2026-11-14)
40
+
41
+
42
+ ### ⚠ BREAKING CHANGES
43
+
44
+ * build the binding on matryona-machines 0.2; read Gains and Limits from the struct; compiler-checked symbols; ship no test files
45
+
46
+ ### Features
47
+
48
+ * build the binding on matryona-machines 0.2; read Gains and Limits from the struct; compiler-checked symbols; ship no test files ([19023a5](https://github.com/seuros/feedback_machines/commit/19023a591da9a54ecb606eab51a9cc035eccf7a7))
49
+
50
+ ## [0.3.0](https://github.com/seuros/feedback_machines/compare/feedback_machines/v0.2.0...feedback_machines/v0.3.0) (2026-11-14)
51
+
52
+
53
+ ### ⚠ BREAKING CHANGES
54
+
55
+ * seal Gains and Limits, re-validate them at the binding, hold no borrow while Limits.new runs
56
+
57
+ ### Features
58
+
59
+ * seal Gains and Limits, re-validate them at the binding, hold no borrow while Limits.new runs ([8aee9ef](https://github.com/seuros/feedback_machines/commit/8aee9efe086af88530c672abd235f92f64d4fb32))
60
+
61
+ ## [0.2.0](https://github.com/seuros/feedback_machines/compare/feedback_machines/v0.1.4...feedback_machines/v0.2.0) (2026-11-13)
62
+
63
+
64
+ ### ⚠ BREAKING CHANGES
65
+
66
+ * converted to the fleet conventions. One exhaustive Refusal per crate, Result from every operation that can refuse, a refusal changes nothing, provable idempotent repeats are honoured, Ruby mirrors the core. No compatibility aliases. step and observe return Result; Ruby takes Gains and Limits values.
67
+
68
+ ### Features
69
+
70
+ * refuse bad samples with Refusal and take elapsed as Integer nanoseconds in Ruby ([cc23741](https://github.com/seuros/feedback_machines/commit/cc23741e0f1309717910b8752b14e6bbef1dcf13))
71
+
3
72
  ## [0.1.4](https://github.com/seuros/feedback_machines/compare/feedback_machines/v0.1.3...feedback_machines/v0.1.4) (2026-11-06)
4
73
 
5
74
 
data/Cargo.lock ADDED
@@ -0,0 +1,307 @@
1
+ # This file is automatically @generated by Cargo.
2
+ # It is not intended for manual editing.
3
+ version = 4
4
+
5
+ [[package]]
6
+ name = "aho-corasick"
7
+ version = "1.1.5"
8
+ source = "registry+https://github.com/rust-lang/crates.io-index"
9
+ checksum = "c982642fa9e8606056828ee9a8505737230110bb1099153c79efe865c59d12ba"
10
+ dependencies = [
11
+ "memchr",
12
+ ]
13
+
14
+ [[package]]
15
+ name = "bindgen"
16
+ version = "0.72.1"
17
+ source = "registry+https://github.com/rust-lang/crates.io-index"
18
+ checksum = "993776b509cfb49c750f11b8f07a46fa23e0a1386ffc01fb1e7d343efc387895"
19
+ dependencies = [
20
+ "bitflags",
21
+ "cexpr",
22
+ "clang-sys",
23
+ "itertools",
24
+ "proc-macro2",
25
+ "quote",
26
+ "regex",
27
+ "rustc-hash",
28
+ "shlex",
29
+ "syn",
30
+ ]
31
+
32
+ [[package]]
33
+ name = "bitflags"
34
+ version = "2.13.2"
35
+ source = "registry+https://github.com/rust-lang/crates.io-index"
36
+ checksum = "3ded4057c258ba199e2d26386d3af3780957ecaee6c4ef4041c6b4b8b97c0b06"
37
+
38
+ [[package]]
39
+ name = "bytes"
40
+ version = "1.12.1"
41
+ source = "registry+https://github.com/rust-lang/crates.io-index"
42
+ checksum = "fc652a48c352aef3ea3aed32080501cf3ef6ed5da78602a020c991775b0aff04"
43
+
44
+ [[package]]
45
+ name = "cexpr"
46
+ version = "0.6.0"
47
+ source = "registry+https://github.com/rust-lang/crates.io-index"
48
+ checksum = "6fac387a98bb7c37292057cffc56d62ecb629900026402633ae9160df93a8766"
49
+ dependencies = [
50
+ "nom",
51
+ ]
52
+
53
+ [[package]]
54
+ name = "cfg-if"
55
+ version = "1.0.5"
56
+ source = "registry+https://github.com/rust-lang/crates.io-index"
57
+ checksum = "4e7648175b45a9a48536d676f68d918270699102aa8dab5496df06904c914600"
58
+
59
+ [[package]]
60
+ name = "clang-sys"
61
+ version = "1.9.1"
62
+ source = "registry+https://github.com/rust-lang/crates.io-index"
63
+ checksum = "157a8ba7b480713b56f4c09fd13fc3e0a22a5dfab8097ba61cbc5feef950788a"
64
+ dependencies = [
65
+ "glob",
66
+ "libc",
67
+ "libloading",
68
+ ]
69
+
70
+ [[package]]
71
+ name = "either"
72
+ version = "1.19.0"
73
+ source = "registry+https://github.com/rust-lang/crates.io-index"
74
+ checksum = "0e9c71c2167ca323c882b99918929403426e2373ea17242ff5653e0d5e1058be"
75
+
76
+ [[package]]
77
+ name = "feedback-machines"
78
+ version = "0.6.0"
79
+ dependencies = [
80
+ "matryona-machines",
81
+ ]
82
+
83
+ [[package]]
84
+ name = "feedback_machines_native"
85
+ version = "0.1.7"
86
+ dependencies = [
87
+ "feedback-machines",
88
+ "magnus",
89
+ "matryona-machines",
90
+ "rb-sys",
91
+ ]
92
+
93
+ [[package]]
94
+ name = "glob"
95
+ version = "0.3.4"
96
+ source = "registry+https://github.com/rust-lang/crates.io-index"
97
+ checksum = "e4eba85ea1d0a966a983acd07deee566e67395d2d96b6fb39e62b5a833f1eb0b"
98
+
99
+ [[package]]
100
+ name = "itertools"
101
+ version = "0.13.0"
102
+ source = "registry+https://github.com/rust-lang/crates.io-index"
103
+ checksum = "413ee7dfc52ee1a4949ceeb7dbc8a33f2d6c088194d9f922fb8318faf1f01186"
104
+ dependencies = [
105
+ "either",
106
+ ]
107
+
108
+ [[package]]
109
+ name = "lazy_static"
110
+ version = "1.5.1"
111
+ source = "registry+https://github.com/rust-lang/crates.io-index"
112
+ checksum = "20870f649af7073d53e38067b2a84312175d56ea15217e1b15bc83506ec50afb"
113
+
114
+ [[package]]
115
+ name = "libc"
116
+ version = "0.2.191"
117
+ source = "registry+https://github.com/rust-lang/crates.io-index"
118
+ checksum = "65cd87c9a6d60536580b316ad985726104730a5151c99845f2490428ef91240a"
119
+
120
+ [[package]]
121
+ name = "libloading"
122
+ version = "0.8.9"
123
+ source = "registry+https://github.com/rust-lang/crates.io-index"
124
+ checksum = "d7c4b02199fee7c5d21a5ae7d8cfa79a6ef5bb2fc834d6e9058e89c825efdc55"
125
+ dependencies = [
126
+ "cfg-if",
127
+ "windows-link",
128
+ ]
129
+
130
+ [[package]]
131
+ name = "magnus"
132
+ version = "0.9.3"
133
+ source = "registry+https://github.com/rust-lang/crates.io-index"
134
+ checksum = "40ef424404d166cbb71c8b8d19c9c589c748c4547c1afa1928c5504299f6c713"
135
+ dependencies = [
136
+ "bytes",
137
+ "magnus-macros",
138
+ "rb-sys",
139
+ "rb-sys-env",
140
+ "seq-macro",
141
+ ]
142
+
143
+ [[package]]
144
+ name = "magnus-macros"
145
+ version = "0.9.1"
146
+ source = "registry+https://github.com/rust-lang/crates.io-index"
147
+ checksum = "9dafde2eeb66f090e0f326112323eb8324b12cb32b5d1210e541d3df6b0ce77e"
148
+ dependencies = [
149
+ "proc-macro2",
150
+ "quote",
151
+ "syn",
152
+ ]
153
+
154
+ [[package]]
155
+ name = "matryona-machines"
156
+ version = "0.6.0"
157
+ source = "registry+https://github.com/rust-lang/crates.io-index"
158
+ checksum = "cf8a06ab02efd767270815a1f515a40bbf3bfc77038e9360676ebe8d47833b07"
159
+ dependencies = [
160
+ "magnus",
161
+ ]
162
+
163
+ [[package]]
164
+ name = "memchr"
165
+ version = "2.8.3"
166
+ source = "registry+https://github.com/rust-lang/crates.io-index"
167
+ checksum = "cf8baf1c55e62ffcace7a9f06f4bd9cd3f0c4beb022d3b367256b91b87513d98"
168
+
169
+ [[package]]
170
+ name = "minimal-lexical"
171
+ version = "0.2.1"
172
+ source = "registry+https://github.com/rust-lang/crates.io-index"
173
+ checksum = "68354c5c6bd36d73ff3feceb05efa59b6acb7626617f4962be322a825e61f79a"
174
+
175
+ [[package]]
176
+ name = "nom"
177
+ version = "7.1.3"
178
+ source = "registry+https://github.com/rust-lang/crates.io-index"
179
+ checksum = "d273983c5a657a70a3e8f2a01329822f3b8c8172b73826411a55751e404a0a4a"
180
+ dependencies = [
181
+ "memchr",
182
+ "minimal-lexical",
183
+ ]
184
+
185
+ [[package]]
186
+ name = "proc-macro2"
187
+ version = "1.0.107"
188
+ source = "registry+https://github.com/rust-lang/crates.io-index"
189
+ checksum = "985e7ec9bb745e6ce6535b544d84d6cd6f7ad8bd711c398938ae983b91a766d9"
190
+ dependencies = [
191
+ "unicode-ident",
192
+ ]
193
+
194
+ [[package]]
195
+ name = "quote"
196
+ version = "1.0.47"
197
+ source = "registry+https://github.com/rust-lang/crates.io-index"
198
+ checksum = "1fbf4db142a473a8d80c26bbf18454ed458bf8d26c8219c331daecfdbd079001"
199
+ dependencies = [
200
+ "proc-macro2",
201
+ ]
202
+
203
+ [[package]]
204
+ name = "rb-sys"
205
+ version = "0.9.130"
206
+ source = "registry+https://github.com/rust-lang/crates.io-index"
207
+ checksum = "02faf625bb10ba893e3ae620f19c9fb1b5f8fcae0fe4eb86bb3f2230fad75edb"
208
+ dependencies = [
209
+ "rb-sys-build",
210
+ ]
211
+
212
+ [[package]]
213
+ name = "rb-sys-build"
214
+ version = "0.9.130"
215
+ source = "registry+https://github.com/rust-lang/crates.io-index"
216
+ checksum = "05be6f9c86fe5482808162826f6c047d093b3670582296c770de1d94f8066694"
217
+ dependencies = [
218
+ "bindgen",
219
+ "lazy_static",
220
+ "proc-macro2",
221
+ "quote",
222
+ "regex",
223
+ "shell-words",
224
+ "syn",
225
+ ]
226
+
227
+ [[package]]
228
+ name = "rb-sys-env"
229
+ version = "0.2.3"
230
+ source = "registry+https://github.com/rust-lang/crates.io-index"
231
+ checksum = "cca7ad6a7e21e72151d56fe2495a259b5670e204c3adac41ee7ef676ea08117a"
232
+
233
+ [[package]]
234
+ name = "regex"
235
+ version = "1.13.1"
236
+ source = "registry+https://github.com/rust-lang/crates.io-index"
237
+ checksum = "f020237b6c8eed93db2e2cb53c00c60a8e1bc73da7d073199a1180401450218d"
238
+ dependencies = [
239
+ "aho-corasick",
240
+ "memchr",
241
+ "regex-automata",
242
+ "regex-syntax",
243
+ ]
244
+
245
+ [[package]]
246
+ name = "regex-automata"
247
+ version = "0.4.18"
248
+ source = "registry+https://github.com/rust-lang/crates.io-index"
249
+ checksum = "ad8553b9b26413251cbf30e620595c7a41b3887f03da04579c0e6b0d6a06b4b2"
250
+ dependencies = [
251
+ "aho-corasick",
252
+ "memchr",
253
+ "regex-syntax",
254
+ ]
255
+
256
+ [[package]]
257
+ name = "regex-syntax"
258
+ version = "0.8.11"
259
+ source = "registry+https://github.com/rust-lang/crates.io-index"
260
+ checksum = "d6f6ff9a378485b298a5286656da665ba74413d36db0979633275d2e708145d4"
261
+
262
+ [[package]]
263
+ name = "rustc-hash"
264
+ version = "2.1.3"
265
+ source = "registry+https://github.com/rust-lang/crates.io-index"
266
+ checksum = "6b1e7f9a428571be2dc5bc0505c13fb6bf936822b894ec87abf8a08a4e51742d"
267
+
268
+ [[package]]
269
+ name = "seq-macro"
270
+ version = "0.3.6"
271
+ source = "registry+https://github.com/rust-lang/crates.io-index"
272
+ checksum = "1bc711410fbe7399f390ca1c3b60ad0f53f80e95c5eb935e52268a0e2cd49acc"
273
+
274
+ [[package]]
275
+ name = "shell-words"
276
+ version = "1.1.1"
277
+ source = "registry+https://github.com/rust-lang/crates.io-index"
278
+ checksum = "dc6fe69c597f9c37bfeeeeeb33da3530379845f10be461a66d16d03eca2ded77"
279
+
280
+ [[package]]
281
+ name = "shlex"
282
+ version = "1.3.0"
283
+ source = "registry+https://github.com/rust-lang/crates.io-index"
284
+ checksum = "0fda2ff0d084019ba4d7c6f371c95d8fd75ce3524c3cb8fb653a3023f6323e64"
285
+
286
+ [[package]]
287
+ name = "syn"
288
+ version = "2.0.119"
289
+ source = "registry+https://github.com/rust-lang/crates.io-index"
290
+ checksum = "872831b642d1a07999a962a351ed35b955ea2cfc8f3862091e2a240a84f17297"
291
+ dependencies = [
292
+ "proc-macro2",
293
+ "quote",
294
+ "unicode-ident",
295
+ ]
296
+
297
+ [[package]]
298
+ name = "unicode-ident"
299
+ version = "1.0.27"
300
+ source = "registry+https://github.com/rust-lang/crates.io-index"
301
+ checksum = "a2c754d6c33795a1c324727428e5a7dedb5b06195f9890bdbcba760d3e246563"
302
+
303
+ [[package]]
304
+ name = "windows-link"
305
+ version = "0.2.1"
306
+ source = "registry+https://github.com/rust-lang/crates.io-index"
307
+ checksum = "f0805222e57f7521d6a62e36fa9163bc891acd422f971defe97d64e70d0a4fe5"
data/Cargo.toml CHANGED
@@ -10,12 +10,14 @@ license = "MIT"
10
10
 
11
11
  [workspace.dependencies]
12
12
  feedback-machines = { path = "ext/feedback_machines_native/core" }
13
+ matryona-machines = { version = ">=0.6", default-features = false }
13
14
  magnus = { version = "0.9.3", default-features = false }
14
15
  rb-sys = { version = "0.9.130", default-features = false, features = ["stable-api-compiled-fallback"] }
15
16
 
16
17
  [workspace.lints.rust]
17
18
  unsafe_code = "deny"
18
19
  unused_must_use = "warn"
20
+ missing_docs = "warn"
19
21
 
20
22
  [workspace.lints.clippy]
21
23
  all = { level = "warn", priority = -1 }
data/README.md CHANGED
@@ -12,19 +12,24 @@ gem 'feedback_machines'
12
12
 
13
13
  ```ruby
14
14
  # Keep the job queue near 50 pending by adding or removing workers.
15
- pid = FeedbackMachines::Pid.new(p: 0.5, i: 0.1, min: -4.0, max: 4.0)
15
+ Gains = FeedbackMachines::Gains # p, i, d
16
+ Limits = FeedbackMachines::Limits # min, max
17
+
18
+ pid = FeedbackMachines::Pid.new(Gains.new(0.5, 0.1, 0.0), Limits.new(-4.0, 4.0))
19
+ last = Process.clock_gettime(Process::CLOCK_MONOTONIC, :nanosecond)
16
20
 
17
21
  loop do
18
- error = queue.depth - 50
19
- delta = pid.step(error: error, elapsed: seconds_since_last_tick)
20
- pool.resize(pool.size + delta.round) if delta
22
+ now = Process.clock_gettime(Process::CLOCK_MONOTONIC, :nanosecond)
23
+ delta = pid.step(queue.depth - 50, now - last) # error, elapsed nanoseconds
24
+ last = now
25
+ pool.resize(pool.size + delta.round) if delta.is_a?(Float)
21
26
  sleep 1
22
27
  end
23
28
  ```
24
29
 
25
30
  ```ruby
26
31
  # Flip into shed mode above 80% CPU, back out below 60%, nothing in between.
27
- band = FeedbackMachines::Hysteresis.new(min: 0.6, max: 0.8)
32
+ band = FeedbackMachines::Hysteresis.new(Limits.new(0.6, 0.8))
28
33
 
29
34
  shed_mode = band.observe(cpu.utilization) == :high
30
35
  ```
@@ -84,37 +89,45 @@ sequenceDiagram
84
89
 
85
90
  Tick->>Queue: depth?
86
91
  Queue-->>Tick: 70
87
- Tick->>Pid: step(error: 20, elapsed: 1.0)
92
+ Tick->>Pid: step(20, 1_000_000_000)
88
93
  Note over Pid: p: 0.5 × 20 = 10, clamped to 4
89
94
  Pid-->>Tick: 4.0
90
95
  Tick->>Pool: resize(+4)
91
96
 
92
97
  Tick->>Queue: depth?
93
98
  Queue-->>Tick: 54
94
- Tick->>Pid: step(error: 4, elapsed: 1.0)
99
+ Tick->>Pid: step(4, 1_000_000_000)
95
100
  Note over Pid: 2 + integral 0.4
96
101
  Pid-->>Tick: 2.4
97
102
  Tick->>Pool: resize(+2)
98
103
 
99
104
  Tick->>Queue: depth?
100
105
  Queue-->>Tick: 48
101
- Tick->>Pid: step(error: -2, elapsed: 1.0)
106
+ Tick->>Pid: step(-2, 1_000_000_000)
102
107
  Pid-->>Tick: -0.8
103
108
  Tick->>Pool: resize(-1)
104
109
  ```
105
110
 
106
111
  ## How the Pid Works
107
112
 
113
+ Every example below uses these:
114
+
115
+ ```ruby
116
+ Gains = FeedbackMachines::Gains
117
+ Limits = FeedbackMachines::Limits
118
+ SECOND = 1_000_000_000 # elapsed time is Integer nanoseconds
119
+ ```
120
+
108
121
  ### Proportional
109
122
 
110
123
  With only `p` set, the output is the error times the gain, clamped to the limits.
111
124
 
112
125
  ```ruby
113
- pid = FeedbackMachines::Pid.new(p: 1.0, min: -10.0, max: 10.0)
126
+ pid = FeedbackMachines::Pid.new(Gains.new(1.0, 0.0, 0.0), Limits.new(-10.0, 10.0))
114
127
 
115
- pid.step(error: 3.0, elapsed: 1.0) # => 3.0
116
- pid.step(error: -3.0, elapsed: 1.0) # => -3.0
117
- pid.step(error: 30.0, elapsed: 1.0) # => 10.0, clamped
128
+ pid.step(3.0, SECOND) # => 3.0
129
+ pid.step(-3.0, SECOND) # => -3.0
130
+ pid.step(30.0, SECOND) # => 10.0, clamped
118
131
  ```
119
132
 
120
133
  ### Integral, without windup
@@ -122,11 +135,11 @@ pid.step(error: 30.0, elapsed: 1.0) # => 10.0, clamped
122
135
  Add `i` and the controller starts remembering. Each step adds `error × elapsed` to a running total. But when the output is already pinned at a limit, the total stops growing. That's the part that keeps a saturated actuator from accumulating a debt it can never repay.
123
136
 
124
137
  ```ruby
125
- pid = FeedbackMachines::Pid.new(p: 1.0, i: 1.0, min: -10.0, max: 10.0)
138
+ pid = FeedbackMachines::Pid.new(Gains.new(1.0, 1.0, 0.0), Limits.new(-10.0, 10.0))
126
139
 
127
- pid.step(error: 100.0, elapsed: 1.0) # => 10.0, clamped, integral frozen
128
- pid.step(error: 1.0, elapsed: 1.0) # => 2.0, not 101.0
129
- pid.step(error: 1.0, elapsed: 1.0) # => 3.0, integral climbing normally now
140
+ pid.step(100.0, SECOND) # => 10.0, clamped, integral frozen
141
+ pid.step(1.0, SECOND) # => 2.0, not 101.0
142
+ pid.step(1.0, SECOND) # => 3.0, integral climbing normally now
130
143
  ```
131
144
 
132
145
  Without that guard, the second step would try to pay back a hundred units of accumulated error and overshoot for the next minute.
@@ -136,32 +149,34 @@ Without that guard, the second step would try to pay back a hundred units of acc
136
149
  Add `d` and the controller reacts to the *rate* of change. The first step has nothing to compare against, so the derivative term is zero.
137
150
 
138
151
  ```ruby
139
- pid = FeedbackMachines::Pid.new(p: 0.0, d: 1.0, min: -100.0, max: 100.0)
152
+ pid = FeedbackMachines::Pid.new(Gains.new(0.0, 0.0, 1.0), Limits.new(-100.0, 100.0))
140
153
 
141
- pid.step(error: 5.0, elapsed: 1.0) # => 0.0, no history yet
142
- pid.step(error: 6.0, elapsed: 0.5) # => 2.0, rose by 1 over 0.5s
143
- pid.step(error: 6.0, elapsed: 0.5) # => 0.0, holding steady
154
+ pid.step(5.0, SECOND) # => 0.0, no history yet
155
+ pid.step(6.0, SECOND / 2) # => 2.0, rose by 1 over half a second
156
+ pid.step(6.0, SECOND / 2) # => 0.0, holding steady
144
157
  ```
145
158
 
146
159
  ### Bad samples don't poison the history
147
160
 
148
- A zero interval, a NaN reading, or an infinite one returns `nil` and leaves the controller exactly as it was. Skip that tick and carry on.
161
+ A zero interval, a NaN reading, or an infinite one is refused: `step` answers a symbol saying why and leaves the controller exactly as it was. Skip that tick and carry on.
149
162
 
150
163
  ```ruby
151
- pid = FeedbackMachines::Pid.new(p: 1.0, i: 1.0, min: -10.0, max: 10.0)
164
+ pid = FeedbackMachines::Pid.new(Gains.new(1.0, 1.0, 0.0), Limits.new(-10.0, 10.0))
152
165
 
153
- pid.step(error: 2.0, elapsed: 1.0) # => 4.0
154
- pid.step(error: 2.0, elapsed: 0.0) # => nil
155
- pid.step(error: Float::NAN, elapsed: 1.0) # => nil
156
- pid.step(error: 2.0, elapsed: 1.0) # => 6.0, as if the two bad ticks never happened
166
+ pid.step(2.0, SECOND) # => 4.0
167
+ pid.step(2.0, 0) # => :invalid_duration
168
+ pid.step(Float::NAN, SECOND) # => :not_finite
169
+ pid.step(2.0, SECOND) # => 6.0, as if the two bad ticks never happened
157
170
  ```
158
171
 
172
+ An output is always a `Float`, a refusal is always a `Symbol`, and there is never a `nil`.
173
+
159
174
  ## How the Band Works
160
175
 
161
176
  Two thresholds. The band starts `:low` and only goes `:high` when a reading reaches `max`. It only comes back down when a reading falls to `min`. Everything in between keeps whatever it was.
162
177
 
163
178
  ```ruby
164
- band = FeedbackMachines::Hysteresis.new(min: 0.6, max: 0.8)
179
+ band = FeedbackMachines::Hysteresis.new(Limits.new(0.6, 0.8))
165
180
 
166
181
  band.observe(0.7) # => :low, started low, not at max yet
167
182
  band.observe(0.85) # => :high
@@ -169,19 +184,61 @@ band.observe(0.7) # => :high, in the dead zone, holds
169
184
  band.observe(0.79) # => :high, still holds
170
185
  band.observe(0.6) # => :low, reached min
171
186
  band.observe(0.7) # => :low, dead zone again, holds
187
+ band.state # => :low, without observing anything
188
+ ```
189
+
190
+ A non-finite reading answers `:not_finite` and the band keeps its state.
191
+
192
+ ## Saving and restoring
193
+
194
+ A controller's whole state is its readers. Save them and resume later: the restored controller compares equal to the one it was saved from and answers every later sample the same way.
195
+
196
+ ```ruby
197
+ saved = [pid.gains, pid.limits, pid.integral, pid.previous_error]
198
+ pid = FeedbackMachines::Pid.restored(*saved) # previous_error is nil before the first sample
199
+
200
+ band = FeedbackMachines::Hysteresis.restored(band.limits, band.state)
172
201
  ```
173
202
 
174
- A non-finite reading returns `nil` and the band keeps its state.
203
+ `Pid.restored` raises `RangeError` for a non-finite `integral` or `previous_error`, `TypeError` for anything but a Float or Integer (or `nil` for `previous_error`). `Hysteresis.restored` takes `:low` or `:high`.
175
204
 
176
205
  ## The Rules of the Tender
177
206
 
178
- - **Gains are finite and nonnegative.** Negative or infinite `p`, `i`, or `d` raises `ArgumentError`. Flip the sign of your error instead.
179
- - **Limits need `min < max`.** Equal or reversed raises `ArgumentError`. Same for the band.
180
- - **`elapsed` is a duration in seconds**, not a timestamp. Negative or NaN raises `ArgumentError`. Zero returns `nil`.
181
- - **Integers are fine.** `p: 1, min: 0, max: 1` works. Everything is treated as a float.
207
+ - **Configuration is two values, passed positionally.** `Gains.new(p, i, d)` and `Limits.new(min, max)` mirror the core's structs, field for field. `Pid.new(gains, limits)`, `Hysteresis.new(limits)`. There are no keyword shortcuts and no default gains: say all three.
208
+ - **A value is valid or does not exist.** `Gains` and `Limits` validate through the core's own constructors whether the gem built them or you did, `with` included. Wrong type is `TypeError`, a value the core's constructor rejects is `RangeError`. Both classes are sealed: subclassing raises `TypeError` and `allocate` is gone. So are `Pid` and `Hysteresis`. That stops accidents, not reflection, so the binding checks too: `Pid.new` and `Hysteresis.new` take only instances of exactly `Gains` and `Limits` (`TypeError` otherwise, a subclass included) and run their fields through the core's constructors again (`RangeError`), so a value forged with `Data#initialize` or `Marshal` never reaches the core.
209
+ - **Gains are finite and nonnegative.** Negative or infinite `p`, `i`, or `d` raises `RangeError` from `Gains.new`. Flip the sign of your error instead. A `-0.0` gain is stored as `0.0`.
210
+ - **Limits need `min < max`.** Equal, reversed or non-finite raises `RangeError` from `Limits.new`. Same value type for the band.
211
+ - **`elapsed` is a span in Integer nanoseconds**, not a timestamp and not seconds: subtract two `Process.clock_gettime(Process::CLOCK_MONOTONIC, :nanosecond)` readings. A Float raises `TypeError`, a negative one raises `RangeError`. Zero is refused with `:invalid_duration`.
212
+ - **Errors, gains, limits and outputs are Floats.** They are control quantities, not time. Integers are accepted and treated as floats; anything else (a `Rational`, a `BigDecimal`, an object with `to_f`) raises `TypeError`, and no `to_f` runs.
213
+ - **A refusal is a symbol, never an exception, and changes nothing.** Not the integral, not the derivative history, not the band's side.
214
+ - **Nothing to repeat.** Every honoured `step` is a new sample; the controller keeps no record of past calls, so feeding the same sample twice is two samples.
215
+ - **No ids, no clock.** Nothing is issued and nothing reads the time. A controller's state lives in memory; a restart starts from zero unless you saved it (see Saving and restoring).
182
216
  - **Frozen means frozen.** `freeze` a controller or a band and every `step` or `observe` raises `FrozenError`.
183
217
  - **Each controller is its own loop.** Two `Pid` instances share nothing, and they can't be `dup`ed or `clone`d.
184
218
 
219
+ ### Every answer
220
+
221
+ A call that is honoured answers with a value. A call that is not honoured answers with one of the refusal symbols below, the snake_case of a core `Refusal` variant, and changes nothing. There is no catch-all symbol.
222
+
223
+ | Call | Honoured | Records the clock | Refusals |
224
+ | --- | --- | --- | --- |
225
+ | `Gains.new(p, i, d)` | `Gains` | no clock | none; an invalid gain raises `RangeError` |
226
+ | `Limits.new(min, max)` | `Limits` | no clock | none; an invalid range raises `RangeError` |
227
+ | `Pid.new(gains, limits)` | `Pid` | no clock | none |
228
+ | `Pid#step(error, elapsed)` | `Float` within the limits | no, `elapsed` is a span | `:not_finite` (error is NaN or infinite), `:invalid_duration` (elapsed is zero), `:overflow` (a term of the calculation is not finite) |
229
+ | `Pid.restored(gains, limits, integral, previous_error)` | `Pid` | no clock | none; a non-finite integral or previous error raises `RangeError` |
230
+ | `Pid#gains`, `Pid#limits` | `Gains`, `Limits` | no, a query | none, a query |
231
+ | `Pid#integral`, `Pid#previous_error` | `Float`, `Float` or `nil` | no, a query | none, a query |
232
+ | `Hysteresis.new(limits)` | `Hysteresis`, starting `:low` | no clock | none |
233
+ | `Hysteresis.restored(limits, state)` | `Hysteresis` on `state` | no clock | none; a non-Symbol raises `TypeError`, a Symbol other than `:low`/`:high` `RangeError` |
234
+ | `Hysteresis#observe(value)` | `:low`, `:high` | no clock | `:not_finite` |
235
+ | `Hysteresis#state` | `:low`, `:high` | no, a query | none, a query |
236
+ | `Hysteresis#limits` | `Limits` | no, a query | none, a query |
237
+
238
+ No answer records a clock, because there is none: `elapsed` is a span the caller measured, not an instant, and the controllers keep no "latest time". Nothing here can answer a time regression.
239
+
240
+ Everything that can raise (a non-number, a non-Integer or out-of-range `elapsed`, a frozen receiver) is checked before the core runs. A call that raised stepped nothing.
241
+
185
242
  ## What You Think You're Doing vs Reality
186
243
 
187
244
  ### You Think: "I'll just add a worker when the queue is over 100."
@@ -191,7 +248,7 @@ A threshold reacts to where you are. It has no idea how fast you got there or ho
191
248
 
192
249
  ## What's Yours
193
250
 
194
- The controller doesn't read sensors, run timers, or touch actuators. You decide what "error" means, how often to sample, what to do with the number that comes back, and what gains make sense for your system. Start with `p` alone, add `i` when the system settles short of the target, add `d` only if it overshoots.
251
+ The controller doesn't read sensors, run timers, or touch actuators. You decide what "error" means, how often to sample, what to do with the number that comes back, and what gains make sense for your system. Start with `p` alone and zero for the other two, raise `i` when the system settles short of the target, raise `d` only if it overshoots.
195
252
 
196
253
  ## License
197
254