latticerb 0.3.0 → 0.4.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.
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: e1cd02dabe1821baf68283ad31fb90aa688bd1642943fa2f5d914cad759389fe
4
- data.tar.gz: 4c1f1118737aa6fe2a2917db077fd6badf3f03fc169c110bf5c5255a1b8376aa
3
+ metadata.gz: e8b8ff092e386afd2f650b4b9915d837bab09cae92817516403ec373beba6997
4
+ data.tar.gz: 4b68178ac100e814c2613a3bd8ec724a60701fb5ae36a3f93038743f167a4b1a
5
5
  SHA512:
6
- metadata.gz: '087a54e0c2896d3a71ffb4eb8737dbf3ad2a0e04ed36682d8fa232cee7b7a131f706cdf5456277c2c6b3eef59446c263dd8ff4277879345160b386c64b06f8d0'
7
- data.tar.gz: 0fceafc2667a8042a38c7dc292b42d185b7305cf57cbf2a7d21bab7d1915723d0fd5fb33c27a444a349b9bff148357a7313f55542af393a69cf69402551426f3
6
+ metadata.gz: 0a33e59f0410f46973d5282ed63113567c4aa0c83f5f337436abc65cd37efe300b8cd30a8d3569c296cc3690e9d71d15fe847b0e58a880e039b992e342889aef
7
+ data.tar.gz: 3338d9ee6b71c1f8b5acac50b68139be4570da152efc58994a4ed73f33c730ccf649e6492b6fb522a7509b9c65ed8f46be45b7fe069e1b5485540f89bb86e522
data/Cargo.lock ADDED
@@ -0,0 +1,288 @@
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 = "cexpr"
40
+ version = "0.6.0"
41
+ source = "registry+https://github.com/rust-lang/crates.io-index"
42
+ checksum = "6fac387a98bb7c37292057cffc56d62ecb629900026402633ae9160df93a8766"
43
+ dependencies = [
44
+ "nom",
45
+ ]
46
+
47
+ [[package]]
48
+ name = "cfg-if"
49
+ version = "1.0.5"
50
+ source = "registry+https://github.com/rust-lang/crates.io-index"
51
+ checksum = "4e7648175b45a9a48536d676f68d918270699102aa8dab5496df06904c914600"
52
+
53
+ [[package]]
54
+ name = "clang-sys"
55
+ version = "1.9.1"
56
+ source = "registry+https://github.com/rust-lang/crates.io-index"
57
+ checksum = "157a8ba7b480713b56f4c09fd13fc3e0a22a5dfab8097ba61cbc5feef950788a"
58
+ dependencies = [
59
+ "glob",
60
+ "libc",
61
+ "libloading",
62
+ ]
63
+
64
+ [[package]]
65
+ name = "either"
66
+ version = "1.19.0"
67
+ source = "registry+https://github.com/rust-lang/crates.io-index"
68
+ checksum = "0e9c71c2167ca323c882b99918929403426e2373ea17242ff5653e0d5e1058be"
69
+
70
+ [[package]]
71
+ name = "glob"
72
+ version = "0.3.4"
73
+ source = "registry+https://github.com/rust-lang/crates.io-index"
74
+ checksum = "e4eba85ea1d0a966a983acd07deee566e67395d2d96b6fb39e62b5a833f1eb0b"
75
+
76
+ [[package]]
77
+ name = "itertools"
78
+ version = "0.13.0"
79
+ source = "registry+https://github.com/rust-lang/crates.io-index"
80
+ checksum = "413ee7dfc52ee1a4949ceeb7dbc8a33f2d6c088194d9f922fb8318faf1f01186"
81
+ dependencies = [
82
+ "either",
83
+ ]
84
+
85
+ [[package]]
86
+ name = "lattice-engine"
87
+ version = "0.1.0"
88
+ source = "registry+https://github.com/rust-lang/crates.io-index"
89
+ checksum = "b686b7e557fb3f0246835e631958e8faaa44687e9afc2356ccd85438a952be92"
90
+
91
+ [[package]]
92
+ name = "lattice_native"
93
+ version = "0.4.0"
94
+ dependencies = [
95
+ "lattice-engine",
96
+ "magnus",
97
+ ]
98
+
99
+ [[package]]
100
+ name = "lazy_static"
101
+ version = "1.5.1"
102
+ source = "registry+https://github.com/rust-lang/crates.io-index"
103
+ checksum = "20870f649af7073d53e38067b2a84312175d56ea15217e1b15bc83506ec50afb"
104
+
105
+ [[package]]
106
+ name = "libc"
107
+ version = "0.2.191"
108
+ source = "registry+https://github.com/rust-lang/crates.io-index"
109
+ checksum = "65cd87c9a6d60536580b316ad985726104730a5151c99845f2490428ef91240a"
110
+
111
+ [[package]]
112
+ name = "libloading"
113
+ version = "0.8.9"
114
+ source = "registry+https://github.com/rust-lang/crates.io-index"
115
+ checksum = "d7c4b02199fee7c5d21a5ae7d8cfa79a6ef5bb2fc834d6e9058e89c825efdc55"
116
+ dependencies = [
117
+ "cfg-if",
118
+ "windows-link",
119
+ ]
120
+
121
+ [[package]]
122
+ name = "magnus"
123
+ version = "0.9.3"
124
+ source = "registry+https://github.com/rust-lang/crates.io-index"
125
+ checksum = "40ef424404d166cbb71c8b8d19c9c589c748c4547c1afa1928c5504299f6c713"
126
+ dependencies = [
127
+ "magnus-macros",
128
+ "rb-sys",
129
+ "rb-sys-env",
130
+ "seq-macro",
131
+ ]
132
+
133
+ [[package]]
134
+ name = "magnus-macros"
135
+ version = "0.9.1"
136
+ source = "registry+https://github.com/rust-lang/crates.io-index"
137
+ checksum = "9dafde2eeb66f090e0f326112323eb8324b12cb32b5d1210e541d3df6b0ce77e"
138
+ dependencies = [
139
+ "proc-macro2",
140
+ "quote",
141
+ "syn",
142
+ ]
143
+
144
+ [[package]]
145
+ name = "memchr"
146
+ version = "2.8.3"
147
+ source = "registry+https://github.com/rust-lang/crates.io-index"
148
+ checksum = "cf8baf1c55e62ffcace7a9f06f4bd9cd3f0c4beb022d3b367256b91b87513d98"
149
+
150
+ [[package]]
151
+ name = "minimal-lexical"
152
+ version = "0.2.1"
153
+ source = "registry+https://github.com/rust-lang/crates.io-index"
154
+ checksum = "68354c5c6bd36d73ff3feceb05efa59b6acb7626617f4962be322a825e61f79a"
155
+
156
+ [[package]]
157
+ name = "nom"
158
+ version = "7.1.3"
159
+ source = "registry+https://github.com/rust-lang/crates.io-index"
160
+ checksum = "d273983c5a657a70a3e8f2a01329822f3b8c8172b73826411a55751e404a0a4a"
161
+ dependencies = [
162
+ "memchr",
163
+ "minimal-lexical",
164
+ ]
165
+
166
+ [[package]]
167
+ name = "proc-macro2"
168
+ version = "1.0.107"
169
+ source = "registry+https://github.com/rust-lang/crates.io-index"
170
+ checksum = "985e7ec9bb745e6ce6535b544d84d6cd6f7ad8bd711c398938ae983b91a766d9"
171
+ dependencies = [
172
+ "unicode-ident",
173
+ ]
174
+
175
+ [[package]]
176
+ name = "quote"
177
+ version = "1.0.47"
178
+ source = "registry+https://github.com/rust-lang/crates.io-index"
179
+ checksum = "1fbf4db142a473a8d80c26bbf18454ed458bf8d26c8219c331daecfdbd079001"
180
+ dependencies = [
181
+ "proc-macro2",
182
+ ]
183
+
184
+ [[package]]
185
+ name = "rb-sys"
186
+ version = "0.9.130"
187
+ source = "registry+https://github.com/rust-lang/crates.io-index"
188
+ checksum = "02faf625bb10ba893e3ae620f19c9fb1b5f8fcae0fe4eb86bb3f2230fad75edb"
189
+ dependencies = [
190
+ "rb-sys-build",
191
+ ]
192
+
193
+ [[package]]
194
+ name = "rb-sys-build"
195
+ version = "0.9.130"
196
+ source = "registry+https://github.com/rust-lang/crates.io-index"
197
+ checksum = "05be6f9c86fe5482808162826f6c047d093b3670582296c770de1d94f8066694"
198
+ dependencies = [
199
+ "bindgen",
200
+ "lazy_static",
201
+ "proc-macro2",
202
+ "quote",
203
+ "regex",
204
+ "shell-words",
205
+ "syn",
206
+ ]
207
+
208
+ [[package]]
209
+ name = "rb-sys-env"
210
+ version = "0.2.3"
211
+ source = "registry+https://github.com/rust-lang/crates.io-index"
212
+ checksum = "cca7ad6a7e21e72151d56fe2495a259b5670e204c3adac41ee7ef676ea08117a"
213
+
214
+ [[package]]
215
+ name = "regex"
216
+ version = "1.13.1"
217
+ source = "registry+https://github.com/rust-lang/crates.io-index"
218
+ checksum = "f020237b6c8eed93db2e2cb53c00c60a8e1bc73da7d073199a1180401450218d"
219
+ dependencies = [
220
+ "aho-corasick",
221
+ "memchr",
222
+ "regex-automata",
223
+ "regex-syntax",
224
+ ]
225
+
226
+ [[package]]
227
+ name = "regex-automata"
228
+ version = "0.4.18"
229
+ source = "registry+https://github.com/rust-lang/crates.io-index"
230
+ checksum = "ad8553b9b26413251cbf30e620595c7a41b3887f03da04579c0e6b0d6a06b4b2"
231
+ dependencies = [
232
+ "aho-corasick",
233
+ "memchr",
234
+ "regex-syntax",
235
+ ]
236
+
237
+ [[package]]
238
+ name = "regex-syntax"
239
+ version = "0.8.11"
240
+ source = "registry+https://github.com/rust-lang/crates.io-index"
241
+ checksum = "d6f6ff9a378485b298a5286656da665ba74413d36db0979633275d2e708145d4"
242
+
243
+ [[package]]
244
+ name = "rustc-hash"
245
+ version = "2.1.3"
246
+ source = "registry+https://github.com/rust-lang/crates.io-index"
247
+ checksum = "6b1e7f9a428571be2dc5bc0505c13fb6bf936822b894ec87abf8a08a4e51742d"
248
+
249
+ [[package]]
250
+ name = "seq-macro"
251
+ version = "0.3.6"
252
+ source = "registry+https://github.com/rust-lang/crates.io-index"
253
+ checksum = "1bc711410fbe7399f390ca1c3b60ad0f53f80e95c5eb935e52268a0e2cd49acc"
254
+
255
+ [[package]]
256
+ name = "shell-words"
257
+ version = "1.1.1"
258
+ source = "registry+https://github.com/rust-lang/crates.io-index"
259
+ checksum = "dc6fe69c597f9c37bfeeeeeb33da3530379845f10be461a66d16d03eca2ded77"
260
+
261
+ [[package]]
262
+ name = "shlex"
263
+ version = "1.3.0"
264
+ source = "registry+https://github.com/rust-lang/crates.io-index"
265
+ checksum = "0fda2ff0d084019ba4d7c6f371c95d8fd75ce3524c3cb8fb653a3023f6323e64"
266
+
267
+ [[package]]
268
+ name = "syn"
269
+ version = "2.0.119"
270
+ source = "registry+https://github.com/rust-lang/crates.io-index"
271
+ checksum = "872831b642d1a07999a962a351ed35b955ea2cfc8f3862091e2a240a84f17297"
272
+ dependencies = [
273
+ "proc-macro2",
274
+ "quote",
275
+ "unicode-ident",
276
+ ]
277
+
278
+ [[package]]
279
+ name = "unicode-ident"
280
+ version = "1.0.27"
281
+ source = "registry+https://github.com/rust-lang/crates.io-index"
282
+ checksum = "a2c754d6c33795a1c324727428e5a7dedb5b06195f9890bdbcba760d3e246563"
283
+
284
+ [[package]]
285
+ name = "windows-link"
286
+ version = "0.2.1"
287
+ source = "registry+https://github.com/rust-lang/crates.io-index"
288
+ checksum = "f0805222e57f7521d6a62e36fa9163bc891acd422f971defe97d64e70d0a4fe5"
data/Cargo.toml ADDED
@@ -0,0 +1,7 @@
1
+ [workspace]
2
+ members = ["ext/lattice_native"]
3
+ resolver = "3"
4
+
5
+ [profile.release]
6
+ lto = true
7
+ codegen-units = 1
data/README.md CHANGED
@@ -4,7 +4,7 @@ Deterministic combinatorial coverage for constrained variant surfaces — roles,
4
4
 
5
5
  Lattice takes a schema of parameters, values, and constraints and generates a minimal covering array: the smallest practical set of scenarios in which every valid pair (or triple, at strength 3) of values appears at least once. Constraints are honored during generation, so no scenario is ever invalid.
6
6
 
7
- This is the Ruby implementation of [Lattice](https://github.com/tylerklose/lattice) ([lattice-cli on PyPI](https://pypi.org/project/lattice-cli/)). Same schema format, same algorithm, same seeds — **byte-identical output** for the same schema, seed, and pool size. That parity is enforced by the test suite, which runs both implementations and diffs their output. Use whichever runtime your project already has.
7
+ This is the Ruby package of [Lattice](https://github.com/tylerklose/lattice) ([lattice-cli on PyPI](https://pypi.org/project/lattice-cli/)). Both packages generate scenarios with the same Rust engine, so they give **byte-identical output** for the same schema, seed and pool size. The test suite checks that by running both and comparing their output. Use whichever runtime your project already has.
8
8
 
9
9
  ## Install
10
10
 
@@ -19,6 +19,8 @@ or standalone:
19
19
  gem install latticerb
20
20
  ```
21
21
 
22
+ The gem ships precompiled for macOS (Apple Silicon and Intel), Linux (x86-64 and ARM64, glibc and musl) and Windows (x86-64). On other platforms it compiles the engine on install, which needs a Rust toolchain. JRuby isn't supported, because it can't load native extensions. If your Gemfile.lock was created on a Mac and you deploy to Linux, add the platform once: `bundle lock --add-platform x86_64-linux`.
23
+
22
24
  ## Library usage
23
25
 
24
26
  The primary API is designed for test suites:
@@ -60,7 +62,7 @@ Lattice.scenarios(file: "...") # shortcut straight to the hashes
60
62
  Lattice.validate!(schema) # raises Lattice::ValidationError / Lattice::ConstraintError
61
63
  ```
62
64
 
63
- Generation options: `strength:` (default 2 = pairwise), `seed:` (default 42), `pool_size:`, `max_rows:`, `stop_after_coverage:`.
65
+ Generation options: `strength:` (default 2 = pairwise), `seed:` (default 42), `pool_size:` (candidate rows per step, default 16), `max_rows:`, `stop_after_coverage:`.
64
66
 
65
67
  ## CLI usage
66
68
 
@@ -97,7 +99,7 @@ constraints:
97
99
  applies_when: [credit_card]
98
100
  ```
99
101
 
100
- Constraint types: `invalid_pair`, `higher_order`, `forward_dep`, `bidirectional`, `conditional`, `forced`. Run `lattice agent instructions` for the full reference.
102
+ Constraint types: `invalid_pair`, `higher_order`, `forward_dep`, `bidirectional`, `conditional`, `forced`. Every constraint needs a `type` key. Run `lattice agent instructions` for an example of each type.
101
103
 
102
104
  ### Values keep their text
103
105
 
@@ -110,17 +112,45 @@ Every value in a schema (the model name, parameter names and values, and constra
110
112
 
111
113
  Changed in 0.3.0: earlier versions converted unquoted numbers and dates, so `0x1F` became `31`, `1.10` became `1.1`, and some values (`.inf`, timestamps) came out differently in the Ruby and Python implementations.
112
114
 
115
+ ## Performance
116
+
117
+ Generation runs in a Rust engine (the `lattice-engine` crate), in two phases:
118
+
119
+ 1. **Build.** Rows are added greedily. Each row is the best of several candidates (`pool_size:`, default 16), and each candidate picks, value by value, whatever covers the most combinations still uncovered.
120
+ 2. **Shrink.** A row is removed and the gaps are repaired with tabu search, which changes values in the remaining rows without breaking any constraint or forced combination. This repeats while repairs succeed within a fixed step budget.
121
+
122
+ The budget is a number of steps, not a time limit, so the same schema and seed give the same rows on every machine. The rows come out ordered so each adds the most new coverage, which is why `max_rows:` and `stop_after_coverage:` cut the set short with as much coverage as possible.
123
+
124
+ Scenario counts against [PICT](https://github.com/microsoft/pict) 3.7, with default settings for both:
125
+
126
+ | Model | PICT | Lattice 0.4 | Lattice 0.3 |
127
+ |---|---|---|---|
128
+ | 13 parameters × 3 values | 20 | **15** (best known) | 22 |
129
+ | 100 × 2 | 16 | **10** (optimal) | over 60 s |
130
+ | 61 mixed (4^15 3^17 2^29) | 40 | **30** | over 60 s |
131
+ | 12 × 6 | 70 | **60** | 88 (32 s) |
132
+ | 30 × 5 | 66 | **55** | over 60 s |
133
+ | 20 × 10 | 218 | **192** | over 60 s |
134
+ | Strength 3, 10 × 4 | 158 | **140** | 176 (27 s) |
135
+
136
+ Each Lattice 0.4 run above takes 0.04–1.2 s on an Apple M-series laptop. PICT is faster (about 0.02 s) because it stops after the build phase.
137
+
138
+ Changed in 0.4.0: rows differ from 0.3.x for the same seed, and every example needs the same number of scenarios or fewer. `pool_size:` now sets the candidates per row; its default went from 50 to 16.
139
+
113
140
  ## Parity with the Python implementation
114
141
 
115
- The generator seeds an MT19937 RNG that reproduces CPython's `random.Random` bit-for-bit, so both implementations walk the same candidate pools and pick the same rows. `test/python_parity_test.rb` shells out to the Python implementation (checkout via `LATTICE_PYTHON_SRC`, or an installed `lattice-cli`) and asserts byte-equal output across formats, seeds, strengths, and stopping rules; it skips when no Python implementation is available.
142
+ Both packages parse schemas in their own language and hand the engine the same compiled constraints (`ConstraintEngine#engine_constraints` here, `lattice.ipog` in Python), so the engine gets identical input. `test/python_parity_test.rb` shells out to the Python implementation (checkout via `LATTICE_PYTHON_SRC`, or an installed `lattice-cli`) and asserts byte-equal output across formats, seeds, strengths and stopping rules; it skips when no Python implementation is available.
116
143
 
117
144
  Schemas are read with Psych here and PyYAML in Python, but both implementations build values from the parsed text with the same rules (see "Values keep their text"), so a schema means the same thing in either. `test/fixtures/scalar_text.*` pins those rules for both.
118
145
 
119
146
  ## Development
120
147
 
148
+ Building the extension needs a Rust toolchain (`rustup`); the engine comes from crates.io (`lattice-engine`).
149
+
121
150
  ```bash
122
151
  bundle install
123
- bundle exec rake test # unit, golden-parity, and live Python-parity suites
152
+ bundle exec rake compile # builds lib/lattice/lattice_native
153
+ bundle exec rake test # unit, golden-parity, and live Python-parity suites (compiles first)
124
154
  bundle exec mutant run # mutation testing (see docs/mutation-testing.md)
125
155
  ```
126
156
 
@@ -0,0 +1,13 @@
1
+ [package]
2
+ name = "lattice_native"
3
+ version = "0.4.0"
4
+ edition = "2024"
5
+ publish = false
6
+
7
+ [lib]
8
+ name = "lattice_native"
9
+ crate-type = ["cdylib"]
10
+
11
+ [dependencies]
12
+ lattice-engine = { version = "0.1.0", default-features = false }
13
+ magnus = "0.9"
@@ -0,0 +1,6 @@
1
+ # frozen_string_literal: true
2
+
3
+ require "mkmf"
4
+ require "rb_sys/mkmf"
5
+
6
+ create_rust_makefile("lattice/lattice_native")
@@ -0,0 +1 @@
1
+ max_width = 120
@@ -0,0 +1,114 @@
1
+ //! Ruby bindings for the Lattice engine (`Lattice::Engine::Model`).
2
+ //!
3
+ //! `Model.new(sizes, weights, strength, invalid_pairs, requires, higher_order, forced)`
4
+ //! takes a schema compiled to the engine's constraint primitives and answers:
5
+ //! `feasibility` (raises ForcedInfeasible with the forced interaction's index,
6
+ //! or NoValidAssignments), `can_complete?(assignments)`, and `generate(...)`.
7
+ use std::cell::RefCell;
8
+
9
+ use lattice_engine::{Assignment, Engine, Error as EngineError, Model as EngineModel, Options};
10
+ use magnus::{Error, ExceptionClass, Module, Ruby, function, method, prelude::*, value::Lazy};
11
+
12
+ type Pair = (Assignment, Assignment);
13
+
14
+ static ENGINE_ERROR: Lazy<ExceptionClass> = Lazy::new(|ruby| {
15
+ ruby.class_object()
16
+ .const_get::<_, magnus::RModule>("Lattice")
17
+ .and_then(|lattice| lattice.const_get::<_, magnus::RModule>("Engine"))
18
+ .and_then(|engine| engine.const_get("ForcedInfeasible"))
19
+ .unwrap()
20
+ });
21
+
22
+ static NO_VALID: Lazy<ExceptionClass> = Lazy::new(|ruby| {
23
+ ruby.class_object()
24
+ .const_get::<_, magnus::RModule>("Lattice")
25
+ .and_then(|lattice| lattice.const_get::<_, magnus::RModule>("Engine"))
26
+ .and_then(|engine| engine.const_get("NoValidAssignments"))
27
+ .unwrap()
28
+ });
29
+
30
+ fn to_ruby(ruby: &Ruby, error: EngineError) -> Error {
31
+ match error {
32
+ EngineError::ForcedInfeasible(index) => Error::new(ruby.get_inner(&ENGINE_ERROR), index.to_string()),
33
+ EngineError::NoValidAssignments => Error::new(ruby.get_inner(&NO_VALID), "no valid assignments"),
34
+ other => Error::new(ruby.exception_arg_error(), format!("{other:?}")),
35
+ }
36
+ }
37
+
38
+ #[magnus::wrap(class = "Lattice::Engine::Model", free_immediately)]
39
+ struct Model(RefCell<Engine>);
40
+
41
+ impl Model {
42
+ fn new(
43
+ ruby: &Ruby,
44
+ sizes: Vec<usize>,
45
+ weights: Vec<Vec<f64>>,
46
+ strength: usize,
47
+ invalid_pairs: Vec<Pair>,
48
+ requires: Vec<Pair>,
49
+ higher_order: Vec<(Vec<Assignment>, Assignment)>,
50
+ forced: Vec<Vec<Assignment>>,
51
+ ) -> Result<Self, Error> {
52
+ let model = EngineModel {
53
+ sizes,
54
+ weights,
55
+ strength,
56
+ invalid_pairs,
57
+ requires,
58
+ higher_order,
59
+ forced,
60
+ };
61
+ Engine::new(model)
62
+ .map(|engine| Model(RefCell::new(engine)))
63
+ .map_err(|e| to_ruby(ruby, e))
64
+ }
65
+
66
+ fn feasibility(ruby: &Ruby, rb_self: &Self) -> Result<(), Error> {
67
+ rb_self.0.borrow_mut().feasibility().map_err(|e| to_ruby(ruby, e))
68
+ }
69
+
70
+ fn can_complete(ruby: &Ruby, rb_self: &Self, assignments: Vec<Assignment>) -> Result<bool, Error> {
71
+ rb_self
72
+ .0
73
+ .borrow_mut()
74
+ .can_complete(&assignments)
75
+ .map_err(|e| to_ruby(ruby, e))
76
+ }
77
+
78
+ /// Returns [rows ordered by coverage, new tuples per row, valid tuples].
79
+ fn generate(
80
+ ruby: &Ruby,
81
+ rb_self: &Self,
82
+ seed: u64,
83
+ candidates: usize,
84
+ shrink_steps: u64,
85
+ patience: u64,
86
+ ) -> Result<(Vec<Vec<usize>>, Vec<usize>, usize), Error> {
87
+ let options = Options {
88
+ seed,
89
+ candidates: candidates.max(1),
90
+ shrink_steps,
91
+ patience,
92
+ };
93
+ let result = rb_self
94
+ .0
95
+ .borrow_mut()
96
+ .generate(&options)
97
+ .map_err(|e| to_ruby(ruby, e))?;
98
+ Ok((result.rows, result.new_coverage, result.valid_tuples))
99
+ }
100
+ }
101
+
102
+ #[magnus::init]
103
+ fn init(ruby: &Ruby) -> Result<(), Error> {
104
+ let engine = ruby.define_module("Lattice")?.define_module("Engine")?;
105
+ let base = engine.define_error("Error", ruby.exception_standard_error())?;
106
+ engine.define_error("ForcedInfeasible", base)?;
107
+ engine.define_error("NoValidAssignments", base)?;
108
+ let model = engine.define_class("Model", ruby.class_object())?;
109
+ model.define_singleton_method("new", function!(Model::new, 7))?;
110
+ model.define_method("feasibility", method!(Model::feasibility, 0))?;
111
+ model.define_method("can_complete?", method!(Model::can_complete, 1))?;
112
+ model.define_method("generate", method!(Model::generate, 4))?;
113
+ Ok(())
114
+ }
data/lib/lattice/agent.rb CHANGED
@@ -21,7 +21,58 @@ module Lattice
21
21
  "template, or config matrix; extract a Lattice schema; validate it; generate pairwise " \
22
22
  "rows; and use the rows to strengthen the plan, tests, fixtures, or visual review."
23
23
 
24
- GENERIC_AGENT_INSTRUCTIONS = <<~INSTRUCTIONS
24
+ SCHEMA_REFERENCE = <<~REFERENCE
25
+
26
+ Schema format, with one example of each constraint type:
27
+
28
+ ```yaml
29
+ model_name: checkout
30
+ strength: 2
31
+ parameters:
32
+ user: [guest, member]
33
+ payment: [card, paypal, apple_pay, invoice]
34
+ device: [desktop, ios, android]
35
+ region: [us, eu]
36
+ currency: [usd, eur]
37
+ shipping: [standard, express, pickup]
38
+ constraints:
39
+ # invalid_pair: these two assignments never appear in the same row.
40
+ - type: invalid_pair
41
+ if: { parameter: payment, value: apple_pay }
42
+ then_not: { parameter: device, value: android }
43
+ # bidirectional: each assignment requires the other.
44
+ - type: bidirectional
45
+ pair:
46
+ - { parameter: region, value: eu }
47
+ - { parameter: currency, value: eur }
48
+ # forward_dep: the source requires the target; the target may appear elsewhere.
49
+ - type: forward_dep
50
+ source: { parameter: shipping, value: pickup }
51
+ target: { parameter: region, value: us }
52
+ # conditional: defines a child parameter that only applies for some parent values.
53
+ - type: conditional
54
+ parameter: card_type
55
+ values: [visa, mastercard]
56
+ parent: payment
57
+ applies_when: [card]
58
+ # forced: this combination must appear in at least one row.
59
+ - type: forced
60
+ assignments:
61
+ - { parameter: user, value: guest }
62
+ - { parameter: device, value: ios }
63
+ - { parameter: shipping, value: express }
64
+ # higher_order: the last assignment is excluded only when all of if_all hold.
65
+ - type: higher_order
66
+ if_all:
67
+ - { parameter: user, value: guest }
68
+ - { parameter: region, value: eu }
69
+ then_not: { parameter: shipping, value: pickup }
70
+ ```
71
+
72
+ Every constraint needs a `type` key. Each assignment is `{ parameter: <name>, value: <value> }`.
73
+ REFERENCE
74
+
75
+ GENERIC_AGENT_INSTRUCTIONS = <<~INSTRUCTIONS + SCHEMA_REFERENCE
25
76
  # Lattice Agent Instructions
26
77
 
27
78
  Lattice is harness-agnostic. Use these instructions in OpenClaw, Hermes, Codex, xAI-backed agents, Claude Code, or any agent that can run shell commands.
data/lib/lattice/cli.rb CHANGED
@@ -59,7 +59,7 @@ module Lattice
59
59
  options = {
60
60
  format: "json",
61
61
  seed: 42,
62
- pool_size: 50,
62
+ pool_size: 16,
63
63
  progress: false,
64
64
  progress_every: 10
65
65
  }
@@ -67,7 +67,7 @@ module Lattice
67
67
  opts.on("--strength STRENGTH", Integer)
68
68
  opts.on("--format FORMAT", %w[table json csv summary yaml])
69
69
  opts.on("--seed SEED", Integer)
70
- opts.on("--pool-size SIZE", Integer) { |value| options[:pool_size] = value }
70
+ opts.on("--pool-size SIZE", Integer, "Candidate rows built per step; more can mean fewer scenarios.") { |value| options[:pool_size] = value }
71
71
  opts.on("--max-rows ROWS", Integer) { |value| options[:max_rows] = value }
72
72
  opts.on("--stop-after-coverage PCT", Float) { |value| options[:stop_after_coverage] = value }
73
73
  opts.on("--progress")
@@ -117,7 +117,7 @@ module Lattice
117
117
  def load_and_check_model(model_path, options)
118
118
  model = Parser.load_model(model_path, strength_override: options[:strength])
119
119
  engine = ConstraintEngine.new(model)
120
- raise ValidationError, ["Model has no valid complete assignments."] unless engine.can_complete?({})
120
+ raise ValidationError, ["Model has no valid complete assignments."] unless engine.satisfiable?
121
121
 
122
122
  model
123
123
  rescue ValidationError => e