hydo-assert 0.0.0-stage → 0.2.0

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.
package/LICENSE ADDED
@@ -0,0 +1,202 @@
1
+
2
+ Apache License
3
+ Version 2.0, January 2004
4
+ http://www.apache.org/licenses/
5
+
6
+ TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
7
+
8
+ 1. Definitions.
9
+
10
+ "License" shall mean the terms and conditions for use, reproduction,
11
+ and distribution as defined by Sections 1 through 9 of this document.
12
+
13
+ "Licensor" shall mean the copyright owner or entity authorized by
14
+ the copyright owner that is granting the License.
15
+
16
+ "Legal Entity" shall mean the union of the acting entity and all
17
+ other entities that control, are controlled by, or are under common
18
+ control with that entity. For the purposes of this definition,
19
+ "control" means (i) the power, direct or indirect, to cause the
20
+ direction or management of such entity, whether by contract or
21
+ otherwise, or (ii) ownership of fifty percent (50%) or more of the
22
+ outstanding shares, or (iii) beneficial ownership of such entity.
23
+
24
+ "You" (or "Your") shall mean an individual or Legal Entity
25
+ exercising permissions granted by this License.
26
+
27
+ "Source" form shall mean the preferred form for making modifications,
28
+ including but not limited to software source code, documentation
29
+ source, and configuration files.
30
+
31
+ "Object" form shall mean any form resulting from mechanical
32
+ transformation or translation of a Source form, including but
33
+ not limited to compiled object code, generated documentation,
34
+ and conversions to other media types.
35
+
36
+ "Work" shall mean the work of authorship, whether in Source or
37
+ Object form, made available under the License, as indicated by a
38
+ copyright notice that is included in or attached to the work
39
+ (an example is provided in the Appendix below).
40
+
41
+ "Derivative Works" shall mean any work, whether in Source or Object
42
+ form, that is based on (or derived from) the Work and for which the
43
+ editorial revisions, annotations, elaborations, or other modifications
44
+ represent, as a whole, an original work of authorship. For the purposes
45
+ of this License, Derivative Works shall not include works that remain
46
+ separable from, or merely link (or bind by name) to the interfaces of,
47
+ the Work and Derivative Works thereof.
48
+
49
+ "Contribution" shall mean any work of authorship, including
50
+ the original version of the Work and any modifications or additions
51
+ to that Work or Derivative Works thereof, that is intentionally
52
+ submitted to Licensor for inclusion in the Work by the copyright owner
53
+ or by an individual or Legal Entity authorized to submit on behalf of
54
+ the copyright owner. For the purposes of this definition, "submitted"
55
+ means any form of electronic, verbal, or written communication sent
56
+ to the Licensor or its representatives, including but not limited to
57
+ communication on electronic mailing lists, source code control systems,
58
+ and issue tracking systems that are managed by, or on behalf of, the
59
+ Licensor for the purpose of discussing and improving the Work, but
60
+ excluding communication that is conspicuously marked or otherwise
61
+ designated in writing by the copyright owner as "Not a Contribution."
62
+
63
+ "Contributor" shall mean Licensor and any individual or Legal Entity
64
+ on behalf of whom a Contribution has been received by Licensor and
65
+ subsequently incorporated within the Work.
66
+
67
+ 2. Grant of Copyright License. Subject to the terms and conditions of
68
+ this License, each Contributor hereby grants to You a perpetual,
69
+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable
70
+ copyright license to reproduce, prepare Derivative Works of,
71
+ publicly display, publicly perform, sublicense, and distribute the
72
+ Work and such Derivative Works in Source or Object form.
73
+
74
+ 3. Grant of Patent License. Subject to the terms and conditions of
75
+ this License, each Contributor hereby grants to You a perpetual,
76
+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable
77
+ (except as stated in this section) patent license to make, have made,
78
+ use, offer to sell, sell, import, and otherwise transfer the Work,
79
+ where such license applies only to those patent claims licensable
80
+ by such Contributor that are necessarily infringed by their
81
+ Contribution(s) alone or by combination of their Contribution(s)
82
+ with the Work to which such Contribution(s) was submitted. If You
83
+ institute patent litigation against any entity (including a
84
+ cross-claim or counterclaim in a lawsuit) alleging that the Work
85
+ or a Contribution incorporated within the Work constitutes direct
86
+ or contributory patent infringement, then any patent licenses
87
+ granted to You under this License for that Work shall terminate
88
+ as of the date such litigation is filed.
89
+
90
+ 4. Redistribution. You may reproduce and distribute copies of the
91
+ Work or Derivative Works thereof in any medium, with or without
92
+ modifications, and in Source or Object form, provided that You
93
+ meet the following conditions:
94
+
95
+ (a) You must give any other recipients of the Work or
96
+ Derivative Works a copy of this License; and
97
+
98
+ (b) You must cause any modified files to carry prominent notices
99
+ stating that You changed the files; and
100
+
101
+ (c) You must retain, in the Source form of any Derivative Works
102
+ that You distribute, all copyright, patent, trademark, and
103
+ attribution notices from the Source form of the Work,
104
+ excluding those notices that do not pertain to any part of
105
+ the Derivative Works; and
106
+
107
+ (d) If the Work includes a "NOTICE" text file as part of its
108
+ distribution, then any Derivative Works that You distribute must
109
+ include a readable copy of the attribution notices contained
110
+ within such NOTICE file, excluding those notices that do not
111
+ pertain to any part of the Derivative Works, in at least one
112
+ of the following places: within a NOTICE text file distributed
113
+ as part of the Derivative Works; within the Source form or
114
+ documentation, if provided along with the Derivative Works; or,
115
+ within a display generated by the Derivative Works, if and
116
+ wherever such third-party notices normally appear. The contents
117
+ of the NOTICE file are for informational purposes only and
118
+ do not modify the License. You may add Your own attribution
119
+ notices within Derivative Works that You distribute, alongside
120
+ or as an addendum to the NOTICE text from the Work, provided
121
+ that such additional attribution notices cannot be construed
122
+ as modifying the License.
123
+
124
+ You may add Your own copyright statement to Your modifications and
125
+ may provide additional or different license terms and conditions
126
+ for use, reproduction, or distribution of Your modifications, or
127
+ for any such Derivative Works as a whole, provided Your use,
128
+ reproduction, and distribution of the Work otherwise complies with
129
+ the conditions stated in this License.
130
+
131
+ 5. Submission of Contributions. Unless You explicitly state otherwise,
132
+ any Contribution intentionally submitted for inclusion in the Work
133
+ by You to the Licensor shall be under the terms and conditions of
134
+ this License, without any additional terms or conditions.
135
+ Notwithstanding the above, nothing herein shall supersede or modify
136
+ the terms of any separate license agreement you may have executed
137
+ with Licensor regarding such Contributions.
138
+
139
+ 6. Trademarks. This License does not grant permission to use the trade
140
+ names, trademarks, service marks, or product names of the Licensor,
141
+ except as required for reasonable and customary use in describing the
142
+ origin of the Work and reproducing the content of the NOTICE file.
143
+
144
+ 7. Disclaimer of Warranty. Unless required by applicable law or
145
+ agreed to in writing, Licensor provides the Work (and each
146
+ Contributor provides its Contributions) on an "AS IS" BASIS,
147
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
148
+ implied, including, without limitation, any warranties or conditions
149
+ of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
150
+ PARTICULAR PURPOSE. You are solely responsible for determining the
151
+ appropriateness of using or redistributing the Work and assume any
152
+ risks associated with Your exercise of permissions under this License.
153
+
154
+ 8. Limitation of Liability. In no event and under no legal theory,
155
+ whether in tort (including negligence), contract, or otherwise,
156
+ unless required by applicable law (such as deliberate and grossly
157
+ negligent acts) or agreed to in writing, shall any Contributor be
158
+ liable to You for damages, including any direct, indirect, special,
159
+ incidental, or consequential damages of any character arising as a
160
+ result of this License or out of the use or inability to use the
161
+ Work (including but not limited to damages for loss of goodwill,
162
+ work stoppage, computer failure or malfunction, or any and all
163
+ other commercial damages or losses), even if such Contributor
164
+ has been advised of the possibility of such damages.
165
+
166
+ 9. Accepting Warranty or Additional Liability. While redistributing
167
+ the Work or Derivative Works thereof, You may choose to offer,
168
+ and charge a fee for, acceptance of support, warranty, indemnity,
169
+ or other liability obligations and/or rights consistent with this
170
+ License. However, in accepting such obligations, You may act only
171
+ on Your own behalf and on Your sole responsibility, not on behalf
172
+ of any other Contributor, and only if You agree to indemnify,
173
+ defend, and hold each Contributor harmless for any liability
174
+ incurred by, or claims asserted against, such Contributor by reason
175
+ of your accepting any such warranty or additional liability.
176
+
177
+ END OF TERMS AND CONDITIONS
178
+
179
+ APPENDIX: How to apply the Apache License to your work.
180
+
181
+ To apply the Apache License to your work, attach the following
182
+ boilerplate notice, with the fields enclosed by brackets "[]"
183
+ replaced with your own identifying information. (Don't include
184
+ the brackets!) The text should be enclosed in the appropriate
185
+ comment syntax for the file format. We also recommend that a
186
+ file or class name and description of purpose be included on the
187
+ same "printed page" as the copyright notice for easier
188
+ identification within third-party archives.
189
+
190
+ Copyright [yyyy] [name of copyright owner]
191
+
192
+ Licensed under the Apache License, Version 2.0 (the "License");
193
+ you may not use this file except in compliance with the License.
194
+ You may obtain a copy of the License at
195
+
196
+ http://www.apache.org/licenses/LICENSE-2.0
197
+
198
+ Unless required by applicable law or agreed to in writing, software
199
+ distributed under the License is distributed on an "AS IS" BASIS,
200
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
201
+ See the License for the specific language governing permissions and
202
+ limitations under the License.
package/README.md CHANGED
@@ -1,3 +1,235 @@
1
- # Temporary Holding Version
1
+ # hydo-assert: the JavaScript assertion SDK (Node.js)
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ A Node.js program running under hydo (the deterministic hypervisor of
4
+ [github.com/kakoc/hydo](https://github.com/kakoc/hydo)) uses this package to say what must be
5
+ true, what should happen at least once, what must happen within a deadline, and where a
6
+ dependency may misbehave. It writes the same console records as the Go SDK (`sdk/go`), byte for
7
+ byte, with the same deduplication rules, so `hydo run` and the explorer (`hydo explore`) read
8
+ them unchanged. The wire format and the verdict rules are in
9
+ `hydo/ASSERTIONS.md` of that repository; paths below are relative to it.
10
+
11
+ The package has no dependencies, works from CommonJS and ESM, and ships TypeScript types.
12
+ Install it from npm (`npm install hydo-assert`), or depend on a checkout by path:
13
+
14
+ ```json
15
+ { "dependencies": { "hydo-assert": "file:../hydo/sdk/js" } }
16
+ ```
17
+
18
+ In a guest image, copy `package.json`, `index.js` and `index.mjs` to
19
+ `/<app>/node_modules/hydo-assert/` (see `hydo/onboard/examples/node-kv/hydo-mac.yaml`).
20
+
21
+ ## Use
22
+
23
+ ```js
24
+ const ha = require('hydo-assert'); // or: import * as ha from 'hydo-assert'
25
+
26
+ // Declare at module top level (load time), so the catalog knows every property up front.
27
+ const ACKED = ha.always('kv.acked_durable', 'every acknowledged write reads back with its value');
28
+ const RECOVERED = ha.sometimes('kv.recovered', 'the server replayed a non-empty log');
29
+ const TORN = ha.reachable('kv.torn_tail', 'the log ended in a partial line');
30
+ const OVERWRITE = ha.unreachable('kv.overwrite', 'a key is never overwritten with another value');
31
+ const LOG_SIZE = ha.always('kv.log_size', 'the log stays under its cap');
32
+ const BACK = ha.eventually('kv.back', 'the server answers within 5 s', 5000);
33
+ const LOST_REPLY = ha.buggify('kv.put.lost_reply', 'the write lands but the reply is lost');
34
+
35
+ ha.catalog(); // once, early, in one process: HYDO-ASSERT-DECL lines
36
+ ACKED.check(got === want, { key: k, got });
37
+ RECOVERED.check(n > 0, { keys: n });
38
+ TORN.hit({ bytes });
39
+ OVERWRITE.hit({ key });
40
+ LOG_SIZE.cmp(size, '<=', cap); // details: left, op, right
41
+ if (LOST_REPLY.fire({ key })) { socket.destroy(); return; }
42
+ await BACK.awaitCond(async () => (await ping()) === 'pong', 100); // one record per episode
43
+ ha.setupComplete(); // HYDO-SETUP-COMPLETE
44
+ ```
45
+
46
+ | Go SDK (`hydoassert`) | JavaScript (`hydo-assert`) |
47
+ |---|---|
48
+ | `Always(id, msg)`, `AlwaysOrUnreachable`, `Sometimes`, `Reachable`, `Unreachable` | `always(id, msg)`, `alwaysOrUnreachable`, `sometimes`, `reachable`, `unreachable` |
49
+ | `a.Check(cond, d)`, `a.Hit(d)` | `a.check(cond, d)` (returns the condition as a boolean), `a.hit(d)` |
50
+ | `a.Cmp(left, op, right, d)` | `a.cmp(left, op, right, d)` (numbers or bigints; `op` is one of `<`, `<=`, `==`, `!=`, `>=`, `>`) |
51
+ | `Eventually(id, msg, within)` | `eventually(id, msg, withinMs)` |
52
+ | `l.Await(cond, poll, d)` | `await l.awaitCond(cond, pollMs, d)` (cond may return a promise); `l.awaitCondSync(cond, pollMs, d)` blocks the thread |
53
+ | `l.Begin()`, `w.Done(d)`, `w.Expire(d)` | `l.begin()`, `w.done(d)`, `w.expire(d)` |
54
+ | `Buggify(id, msg)`, `p.Fire(d)` | `buggify(id, msg)`, `p.fire(d)` |
55
+ | `Catalog()`, `SetupComplete()` | `catalog()`, `setupComplete()` |
56
+ | `D{...}` | a plain object (or a `Map`) |
57
+
58
+ That table, the classes the calls return (`Assertion`, `Liveness`, `Watch`, `Point`) and the
59
+ history recorder below are the whole API, as `index.d.ts` declares it: a comparison has one
60
+ form, `cmp` with its operator. Exports and fields whose names start with `_` and fields that
61
+ `index.d.ts` does not declare are the package's own and may change in any version.
62
+
63
+ ## Records, deduplication, catalog
64
+
65
+ - Records go to `/dev/ttyS0`, opened once (`O_WRONLY|O_APPEND|O_NOCTTY`), one synchronous
66
+ `write` per record (`fs.writeSync`), so a record is never interleaved with other console
67
+ output and is on the console before the call returns. `HYDO_ASSERT_OUT=<path>` writes to that
68
+ existing file, `stderr` to standard error (plain logging outside hydo), `off` nowhere (a
69
+ no-op; BUGGIFY still works). If the file cannot be opened, standard error is used.
70
+ - A process writes each (assertion, outcome) pair once: the first pass and the first failure,
71
+ with the details of that evaluation. A `sometimes` that evaluated false is never written.
72
+ `unreachable` is written with `ok:false`. As in Go, a record whose details cannot be encoded
73
+ (a NaN, an infinity, a cycle) is not written at all, and that outcome still counts as
74
+ written.
75
+ - `catalog()` writes one `HYDO-ASSERT-DECL` line per declared assertion, in declaration order
76
+ (each call writes all of them again, as Go's `Catalog()` does). Declare at module top level,
77
+ so a property in code that never runs is still in the catalog and is reported as never
78
+ evaluated. Under hydo the explorer's runs start from a snapshot taken after the services are
79
+ up, so a long-running server's start-up catalog is not in each run's console: let a
80
+ short-lived process that runs in every run (the oracle, a client) call `catalog()` too, and
81
+ declare the properties in one module that every program loads (as `node-kv/props.cjs` does).
82
+ - "Per process": a worker thread (`worker_threads`) loads its own copy of the module, with its
83
+ own deduplication table. The ESM entry re-exports the CommonJS module, so a program that uses
84
+ both `require` and `import` has one state.
85
+
86
+ ### How details are encoded (exactly as Go's `encoding/json`)
87
+
88
+ | JavaScript value | written as | Go value it matches |
89
+ |---|---|---|
90
+ | object / `Map` | object, keys sorted by their UTF-8 bytes (not by JavaScript's UTF-16 order) | `map[string]any` |
91
+ | array, `Set`, typed arrays other than `Uint8Array` | array | slice |
92
+ | `Uint8Array`, `Buffer` | base64 string | `[]byte` |
93
+ | number | shortest digits; exponent form below 1e-6 and from 1e21 (`1e+21`, `1.5e-7`); `-0` as `-0` | `float64` (and Go integers, which print the same) |
94
+ | bigint | decimal integer | `int64`, `uint64` |
95
+ | string | `"`, `\` escaped; `\b \f \n \r \t`; other control characters `\u00xx`; `<` `>` `&` as `<` `>` `&`; U+2028/U+2029 escaped; a lone surrogate as `�` | `string` (invalid UTF-8 as `�`) |
96
+ | `true`, `false`, `null` | the same | |
97
+ | a value with `toJSON()` (e.g. `Date`) | its result | |
98
+ | `undefined`, function, symbol | left out of objects, `null` in arrays (as `JSON.stringify`) | |
99
+ | NaN, ±Infinity, a cycle | the record is not written | `json.Marshal` fails |
100
+ | details that are not an object (a string, an array) | `{"value": ...}` | |
101
+
102
+ An absent or empty details object gives no `details` field (Go's `omitempty`). `cmp` adds
103
+ `left`/`op`/`right`, `eventually` adds `elapsed_ms`/`within_ms`, and a
104
+ fired fault point adds `hit`: each to the caller's own object (or `Map`) when one is given, as
105
+ the Go SDK writes into the caller's map.
106
+
107
+ **Go version note.** The shared cases hold the bytes of Go 1.26.5, the version this
108
+ repository's Go programs are built with. Go 1.27 changed one detail of `encoding/json`: invalid
109
+ UTF-8 is written as a raw U+FFFD character instead of the escape `\ufffd`. This package
110
+ writes the escape (the Go 1.26 form); everything else is the same for both Go versions.
111
+
112
+ ## Eventually
113
+
114
+ `eventually(id, msg, withinMs)` declares a bounded-liveness property. One episode = one anchor
115
+ and one deadline, measured on the monotonic clock (`process.hrtime`; deterministic under hydo):
116
+
117
+ - `await l.awaitCond(cond, pollMs, d)` anchors now, evaluates `cond` (sync or async) every
118
+ `pollMs` (with `setTimeout`, so the event loop keeps running) until it is true or the
119
+ deadline has passed, writes one record and resolves to the outcome. The last evaluation
120
+ happens at or after the deadline, so a condition that becomes true exactly then still counts.
121
+ - `l.awaitCondSync(cond, pollMs, d)` does the same and blocks the thread between evaluations
122
+ (`Atomics.wait`): only for scripts that have nothing else to do.
123
+ - `w = l.begin()` anchors now; `w.done(d)` records "true now" (ok if in time), `w.expire(d)`
124
+ records a miss. Only the first of them counts for one watch.
125
+
126
+ ## BUGGIFY
127
+
128
+ Same decisions as the Go SDK, bit for bit: configured by `$HYDO_BUGGIFY`, or else the file
129
+ `$HYDO_BUGGIFY_FILE` (default `/tmp/hydo-buggify`), holding
130
+ `<seed-hex>[,<enable-permille>[,<fire-permille>]]` (defaults 250 and 250, FoundationDB's values;
131
+ parsed as Go parses it: hex seed without `0x`, Go's whitespace trimming, a bad enable or fire
132
+ value keeps the default). It is read once, at the first evaluation of any point, which also
133
+ writes `HYDO-BUGGIFY {"seed":..,"enable_pm":..,"fire_pm":..,"enabled":[..]}`. A point is enabled
134
+ for the run when `splitmix64(seed ^ fnv1a(id)) % 1000 < enable`; its k-th evaluation fires when
135
+ `splitmix64(splitmix64(seed ^ fnv1a(id)) + k·0x9e3779b97f4a7c15) % 1000 < fire` (64-bit
136
+ arithmetic with `BigInt`). Each point is also a `sometimes` property `buggify.<id>`
137
+ ("fault point fired: <msg>"), recorded at its first firing with `{"hit": k}`. Without a
138
+ configuration every point returns false and has no other effect. Under hydo the schedule token
139
+ `B=<seed>` (`hydo explore --buggify`) reaches the file through the guest init: an onboarded
140
+ project gets it with `buggify: true` in its `hydo.yaml` (`hydo/onboard/MANIFEST.md`).
141
+
142
+ ## History recorder
143
+
144
+ The entry `hydo-assert/history` records operation histories for hydo's host-side checkers
145
+ (linearizability of a register or compare-and-set object per key, and Elle-style list-append;
146
+ the format and the checkers are in `hydo/HISTORIES.md`). It writes the same `HYDO-HIST` lines as
147
+ the Go recorder (`sdk/go/hydohist`), byte for byte except the time field. It is separate from
148
+ the assertion SDK, so loading it changes nothing the assertion records contain. In a guest
149
+ image, also copy `history.js` and `history.mjs`.
150
+
151
+ ```js
152
+ const hh = require('hydo-assert/history'); // or: import * as hh from 'hydo-assert/history'
153
+
154
+ const kv = new hh.History('kv'); // or hh.history('kv')
155
+ let op = kv.invoke(3, 'write', 'k1', hh.enc(v)); // process 3, before the request
156
+ try {
157
+ const rev = await put('k1', v);
158
+ op.ok('k1', hh.ver(v, rev)); // the version the store assigned, if any
159
+ } catch (e) {
160
+ if (rejected(e)) op.fail(); // it definitely had no effect
161
+ else op.info(); // a timeout: the outcome is unknown
162
+ }
163
+ kv.invoke(3, 'read', 'k1').ok('k1', hh.valueOrNil(await get('k1'))); // null means absent
164
+
165
+ const la = hh.history('la');
166
+ const tx = la.invoke(4, 'txn', hh.append('x', '1'), hh.read('y'));
167
+ tx.ok(hh.append('x', '1'), hh.readResult('y', '1', '2'));
168
+ ```
169
+
170
+ | Go (`hydohist`) | JavaScript (`hydo-assert/history`) |
171
+ |---|---|
172
+ | `New(name)` | `new History(name)` or `history(name)` |
173
+ | `h.Invoke(proc, f, args...)`, `h.Record(proc, typ, f, args...)` | `h.invoke(proc, f, ...args)`, `h.record(proc, type, f, ...args)` |
174
+ | `op.Ok(args...)`, `op.Fail()`, `op.Info()` | `op.ok(...args)` (no args repeats the invocation's), `op.fail()`, `op.info()` |
175
+ | `Enc`, `Ver`, `ValOrNil(v, ok)`, `List` | `enc`, `ver`, `valueOrNil`, `list` |
176
+ | `Append`, `Read`, `ReadResult`, `Nil` | `append`, `read`, `readResult`, `NIL` |
177
+
178
+ - `valueOrNil(v)` treats `null` and `undefined` as absent. `valueOrNil(v, ok)` follows Go: the
179
+ second argument says whether the value is present.
180
+ - A process is an integer or a token without spaces. Arguments are tokens: a string is written
181
+ as it is (encode free-form values with `enc`), and an integer (a number that is an integer,
182
+ or a bigint) is written in decimal. Versions are int64 values; pass a bigint beyond 2^53.
183
+ A value outside int64 throws a `RangeError`, and a value that is not an integer throws a
184
+ `TypeError`.
185
+ - Records go to `/dev/console`. `HYDO_HIST_OUT=<path>` appends to that file and creates it if
186
+ it is missing (mode 0644), `stderr` writes to standard error, and `off` writes nothing. If the
187
+ file cannot be opened, standard error is used. The setting is read once, at the first record,
188
+ and is separate from `HYDO_ASSERT_OUT`.
189
+ - Each record is one `fs.writeSync` call. The time field is `process.hrtime.bigint()`
190
+ (CLOCK_MONOTONIC on Linux, deterministic under hydo). The ESM entry re-exports the CommonJS
191
+ module, so a program that uses both has one sink; a worker thread opens its own.
192
+ - Text is written as UTF-8, and `enc` works on the UTF-8 bytes exactly as Go's `Enc` does. A
193
+ JavaScript string cannot hold invalid UTF-8; a lone surrogate is written (and encoded) as
194
+ U+FFFD, as `Buffer.from` and `TextEncoder` convert it.
195
+ - A process has at most one operation in flight: give each concurrent client its own process
196
+ number. Record the invocation before sending the request and the completion after the reply,
197
+ because the checkers order operations by the position of their records.
198
+
199
+ ## Tests
200
+
201
+ - `npm test` (`node --test test/unit.test.js test/history.test.js`): what the shared cases cannot
202
+ express (cycles, `undefined`, `Map`/`Set`, `Date`, async liveness, the sink switches) and the
203
+ BUGGIFY rates over 400 seeds; for the history recorder, the exact lines of the Go recorder's
204
+ own unit test, the encoding of every byte class, the argument checks, the sink settings and
205
+ one `fs.writeSync` per record.
206
+ - `node --test` (every file in `test/`; `npm test` runs the two unit-test files only) also
207
+ runs `test/cases.test.js`: the shared cases (`sdk/cases`, written by the reference SDK,
208
+ `sdk/rust`; format and rules in `sdk/rust/README.md`, "The shared cases"). For every case
209
+ and run it starts itself as a child process, once through the CommonJS and once through the
210
+ ESM entry, makes the case's calls with this package and `hydo-assert/history`, and compares
211
+ the bytes the sink received and the calls' results with the case's files. Cases that need a
212
+ float32 (`f32`) or invalid UTF-8 bytes in a history record (`raw_hist`, which a JavaScript
213
+ string cannot hold) are skipped and listed. To add a case, add it to the Rust SDK's
214
+ `tests/cases/defs.rs` and run `HYDO_BLESS=1 cargo test --test cases` there; this test then
215
+ runs it. A format change starts in the Rust SDK too: after it is blessed, this test fails on
216
+ the lines this package must change. No other language is needed to run it.
217
+ - `package.json`, `index.js` and `index.mjs` are copied into the node-kv example's images, so
218
+ a change to any of them changes those images' bytes and every node-kv fingerprint (the last
219
+ such change, the `Apache-2.0` license field and the removed `conformance` script of the
220
+ deleted Go-binary harnesses, re-recorded them in milestone 152, and a reworded comment in
221
+ `index.js` in milestone 157; docs/REBASELINE.md has the values).
222
+
223
+ ## Example
224
+
225
+ `hydo/onboard/examples/node-kv/` is a complete example for the Mac backend: a key/value server
226
+ (ESM) and its client and oracle (CommonJS) using this package, the pinned aarch64 Node.js and a
227
+ `hydo-mac.yaml`.
228
+
229
+ ## Limits
230
+
231
+ - Node.js only (it uses `fs`, `Buffer` and `process.hrtime`); not for browsers or Deno/Bun as
232
+ tested targets. Node 16 or later (BigInt, `Atomics.wait`).
233
+ - Each worker thread has its own deduplication table and console file descriptor.
234
+ - No call-site helpers that capture the file and line (the Rust SDK's macros do); declare
235
+ properties with explicit ids.
package/history.d.mts ADDED
@@ -0,0 +1,4 @@
1
+ // Types of hydo-assert/history (ESM entry): the same declarations as the CommonJS entry.
2
+ import m from './history.js';
3
+ export * from './history.js';
4
+ export default m;
package/history.d.ts ADDED
@@ -0,0 +1,56 @@
1
+ // Types of hydo-assert/history (CommonJS entry). The wire format and checkers: hydo/HISTORIES.md.
2
+
3
+ /** A record argument: a string that is already one token (see enc), or an integer. */
4
+ export type Token = string | number | bigint;
5
+
6
+ /** The value of an absent key (register model). */
7
+ export declare const NIL: 'nil';
8
+
9
+ /** One named history (a check's `history:`; [A-Za-z0-9_.-]+). */
10
+ export declare class History {
11
+ constructor(name: string);
12
+ readonly name: string;
13
+ /**
14
+ * Records the invocation of f(args...) by process `proc` (an integer, or a token without
15
+ * spaces) and returns the operation. Record it before sending the request.
16
+ */
17
+ invoke(proc: number | bigint | string, f: string, ...args: Token[]): Op;
18
+ /** Writes one raw record (`type` is invoke, ok, fail or info). */
19
+ record(proc: number | bigint | string, type: 'invoke' | 'ok' | 'fail' | 'info' | string, f: string, ...args: Token[]): void;
20
+ }
21
+
22
+ /** An invoked operation waiting for its completion. */
23
+ export declare class Op {
24
+ private constructor();
25
+ readonly history: History;
26
+ readonly proc: string;
27
+ readonly f: string;
28
+ readonly args: string[];
29
+ /** A successful completion; with no args the invocation's are repeated. */
30
+ ok(...args: Token[]): void;
31
+ /** The operation definitely had no effect. */
32
+ fail(): void;
33
+ /** The outcome is unknown (a timeout, a lost connection). */
34
+ info(): void;
35
+ }
36
+
37
+ /** new History(name). */
38
+ export declare function history(name: string): History;
39
+
40
+ /** One token from a value: Go's hydohist.Enc on the UTF-8 bytes. */
41
+ export declare function enc(v: string | number | bigint): string;
42
+ /** "enc(v)@version" (version: an int64). */
43
+ export declare function ver(v: string | number | bigint, version: number | bigint): string;
44
+ /**
45
+ * enc(v) if present, else NIL. With one argument, null and undefined are absent; with two, the
46
+ * second says whether the value is present (Go's ValOrNil(v, ok)).
47
+ */
48
+ export declare function valueOrNil(v: string | number | bigint | null | undefined, ok?: boolean): string;
49
+ /** "[e1,e2,...]" with each element encoded. */
50
+ export declare function list(...elems: Array<string | number | bigint>): string;
51
+ /** The txn micro-op "a:<k>:<e>". */
52
+ export declare function append(k: string | number | bigint, e: string | number | bigint): string;
53
+ /** The txn micro-op "r:<k>" (invocation). */
54
+ export declare function read(k: string | number | bigint): string;
55
+ /** The txn micro-op "r:<k>:[...]" (completion). */
56
+ export declare function readResult(k: string | number | bigint, ...l: Array<string | number | bigint>): string;