iterate-kernel 0.1.3 → 0.1.5

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.
Files changed (44) hide show
  1. package/README.md +15 -6
  2. package/dist/convergence.d.ts +90 -0
  3. package/dist/convergence.d.ts.map +1 -0
  4. package/dist/convergence.js +97 -0
  5. package/dist/convergence.js.map +1 -0
  6. package/dist/errors.d.ts +15 -0
  7. package/dist/errors.d.ts.map +1 -1
  8. package/dist/errors.js +7 -0
  9. package/dist/errors.js.map +1 -1
  10. package/dist/evidence-pack.d.ts +19 -19
  11. package/dist/index.d.ts +6 -2
  12. package/dist/index.d.ts.map +1 -1
  13. package/dist/index.js +6 -2
  14. package/dist/index.js.map +1 -1
  15. package/dist/invariant-report.d.ts +271 -0
  16. package/dist/invariant-report.d.ts.map +1 -0
  17. package/dist/invariant-report.js +145 -0
  18. package/dist/invariant-report.js.map +1 -0
  19. package/dist/parse.d.ts +9 -0
  20. package/dist/parse.d.ts.map +1 -1
  21. package/dist/parse.js +22 -10
  22. package/dist/parse.js.map +1 -1
  23. package/dist/provider-registration.d.ts +132 -0
  24. package/dist/provider-registration.d.ts.map +1 -0
  25. package/dist/provider-registration.js +119 -0
  26. package/dist/provider-registration.js.map +1 -0
  27. package/dist/run-plan.d.ts +142 -0
  28. package/dist/run-plan.d.ts.map +1 -0
  29. package/dist/run-plan.js +92 -0
  30. package/dist/run-plan.js.map +1 -0
  31. package/dist/schemas.d.ts +10 -0
  32. package/dist/schemas.d.ts.map +1 -1
  33. package/dist/schemas.js +10 -0
  34. package/dist/schemas.js.map +1 -1
  35. package/fixtures/convergence.ok-01.json +252 -0
  36. package/fixtures/invariant-report.ok-01.json +306 -0
  37. package/fixtures/provider-registration.ok-01.json +309 -0
  38. package/fixtures/run-plan.ok-01.json +152 -0
  39. package/package.json +17 -1
  40. package/schemas/convergence-round-state.schema.json +37 -0
  41. package/schemas/invariant-report.schema.json +108 -0
  42. package/schemas/provider-registration.schema.json +63 -0
  43. package/schemas/reverification-request.schema.json +89 -0
  44. package/schemas/run-plan.schema.json +60 -0
@@ -0,0 +1,252 @@
1
+ {
2
+ "comment": "Cross-implementation anchor for the convergence rules (kernel/src/convergence.ts): given what a round states about itself, what the loop does next (5.7 R40 scenario 4). This is policy arithmetic over verdicts somebody else produced — nothing here verifies anything. Rules a second implementation must reproduce, stated here so it need not read the TypeScript: (1) the input object is `iterate.convergence/0.1` (the version key is optional) with required `round` (integer >=1), `maxRounds` (integer >=1), `invariantState` in `pass|fail|error|unmeasured`, `openFindings` (integer >=0), `evidenceComplete` (boolean), `breakerLevel` (integer 0..3, where 3 is tripped); no other keys. (2) PRECEDENCE, first match wins: breakerLevel >= 3 -> halt, reason `circuit-breaker-tripped`; round >= maxRounds -> halt, reason `round-budget-exhausted`; invariantState `error` -> halt, reason `invariant-check-errored`; openFindings > 0 -> fix, reason `open-findings`; invariantState `fail` -> fix, reason `invariants-failed`; evidenceComplete false -> verify, reason `evidence-incomplete`; invariantState `unmeasured` -> verify, reason `invariants-unmeasured`; otherwise -> converged, reason `all-gates-green`. (3) WHY that order: a limit the harness set on itself is not the app's failure, so the breaker halts before anything is counted; the budget is checked before the work so a run cannot buy another round by re-reporting findings it already had; a check that errored yields no verdict, and retrying it is the runner's job, not the loop's; `verify` rather than `converged` for unlooked-or-unmeasured states is the whole point — 'we could not look' and 'we looked and it holds' must not collapse into the same line. (4) The decision echoes `round` and `maxRounds` unchanged, so a ledger line says which round was judged. (5) `breakerLevel` is the engine's own circuit-breaker level for the run; 3 is the policy limit, which is why the range stops there. PROVENANCE: max_rounds 7 is the repo's own `config/iterate.config.yaml`; the breaker ceiling of 3 is `CircuitBreakerLevelSchema` in the evidence-pack contract; each case below states its inputs and the reason the precedence gives, and the expected values were derived from the rule text in this file — not by running the TypeScript.",
3
+ "input": {
4
+ "schemaVersion": "iterate.convergence/0.1",
5
+ "round": 3,
6
+ "maxRounds": 7,
7
+ "invariantState": "pass",
8
+ "openFindings": 0,
9
+ "evidenceComplete": true,
10
+ "breakerLevel": 0
11
+ },
12
+ "expectedDecision": {
13
+ "action": "converged",
14
+ "reason": "all-gates-green",
15
+ "round": 3,
16
+ "maxRounds": 7
17
+ },
18
+ "cases": [
19
+ {
20
+ "name": "breaker-tripped-beats-a-clean-round",
21
+ "state": {
22
+ "round": 1,
23
+ "maxRounds": 7,
24
+ "invariantState": "pass",
25
+ "openFindings": 0,
26
+ "evidenceComplete": true,
27
+ "breakerLevel": 3
28
+ },
29
+ "expect": {
30
+ "action": "halt",
31
+ "reason": "circuit-breaker-tripped",
32
+ "round": 1,
33
+ "maxRounds": 7
34
+ }
35
+ },
36
+ {
37
+ "name": "budget-spent-beats-open-findings",
38
+ "state": {
39
+ "round": 7,
40
+ "maxRounds": 7,
41
+ "invariantState": "fail",
42
+ "openFindings": 2,
43
+ "evidenceComplete": true,
44
+ "breakerLevel": 0
45
+ },
46
+ "expect": {
47
+ "action": "halt",
48
+ "reason": "round-budget-exhausted",
49
+ "round": 7,
50
+ "maxRounds": 7
51
+ }
52
+ },
53
+ {
54
+ "name": "errored-check-beats-open-findings",
55
+ "state": {
56
+ "round": 3,
57
+ "maxRounds": 7,
58
+ "invariantState": "error",
59
+ "openFindings": 1,
60
+ "evidenceComplete": false,
61
+ "breakerLevel": 0
62
+ },
63
+ "expect": {
64
+ "action": "halt",
65
+ "reason": "invariant-check-errored",
66
+ "round": 3,
67
+ "maxRounds": 7
68
+ }
69
+ },
70
+ {
71
+ "name": "open-findings-beats-failed-invariants",
72
+ "state": {
73
+ "round": 2,
74
+ "maxRounds": 7,
75
+ "invariantState": "fail",
76
+ "openFindings": 1,
77
+ "evidenceComplete": true,
78
+ "breakerLevel": 0
79
+ },
80
+ "expect": {
81
+ "action": "fix",
82
+ "reason": "open-findings",
83
+ "round": 2,
84
+ "maxRounds": 7
85
+ }
86
+ },
87
+ {
88
+ "name": "failed-invariants-with-no-findings-still-fix",
89
+ "state": {
90
+ "round": 2,
91
+ "maxRounds": 7,
92
+ "invariantState": "fail",
93
+ "openFindings": 0,
94
+ "evidenceComplete": true,
95
+ "breakerLevel": 0
96
+ },
97
+ "expect": {
98
+ "action": "fix",
99
+ "reason": "invariants-failed",
100
+ "round": 2,
101
+ "maxRounds": 7
102
+ }
103
+ },
104
+ {
105
+ "name": "pass-with-incomplete-evidence-is-not-converged",
106
+ "state": {
107
+ "round": 2,
108
+ "maxRounds": 7,
109
+ "invariantState": "pass",
110
+ "openFindings": 0,
111
+ "evidenceComplete": false,
112
+ "breakerLevel": 0
113
+ },
114
+ "expect": {
115
+ "action": "verify",
116
+ "reason": "evidence-incomplete",
117
+ "round": 2,
118
+ "maxRounds": 7
119
+ }
120
+ },
121
+ {
122
+ "name": "incomplete-evidence-beats-unmeasured-invariants",
123
+ "state": {
124
+ "round": 2,
125
+ "maxRounds": 7,
126
+ "invariantState": "unmeasured",
127
+ "openFindings": 0,
128
+ "evidenceComplete": false,
129
+ "breakerLevel": 0
130
+ },
131
+ "expect": {
132
+ "action": "verify",
133
+ "reason": "evidence-incomplete",
134
+ "round": 2,
135
+ "maxRounds": 7
136
+ }
137
+ },
138
+ {
139
+ "name": "unmeasured-invariants-with-evidence",
140
+ "state": {
141
+ "round": 2,
142
+ "maxRounds": 7,
143
+ "invariantState": "unmeasured",
144
+ "openFindings": 0,
145
+ "evidenceComplete": true,
146
+ "breakerLevel": 0
147
+ },
148
+ "expect": {
149
+ "action": "verify",
150
+ "reason": "invariants-unmeasured",
151
+ "round": 2,
152
+ "maxRounds": 7
153
+ }
154
+ },
155
+ {
156
+ "name": "breaker-level-two-is-not-tripped",
157
+ "state": {
158
+ "round": 2,
159
+ "maxRounds": 7,
160
+ "invariantState": "pass",
161
+ "openFindings": 0,
162
+ "evidenceComplete": true,
163
+ "breakerLevel": 2
164
+ },
165
+ "expect": {
166
+ "action": "converged",
167
+ "reason": "all-gates-green",
168
+ "round": 2,
169
+ "maxRounds": 7
170
+ }
171
+ },
172
+ {
173
+ "name": "zero-round",
174
+ "state": {
175
+ "round": 0,
176
+ "maxRounds": 7,
177
+ "invariantState": "pass",
178
+ "openFindings": 0,
179
+ "evidenceComplete": true,
180
+ "breakerLevel": 0
181
+ },
182
+ "expect": "refused",
183
+ "path": "round"
184
+ },
185
+ {
186
+ "name": "breaker-level-out-of-range",
187
+ "state": {
188
+ "round": 1,
189
+ "maxRounds": 7,
190
+ "invariantState": "pass",
191
+ "openFindings": 0,
192
+ "evidenceComplete": true,
193
+ "breakerLevel": 4
194
+ },
195
+ "expect": "refused",
196
+ "path": "breakerLevel"
197
+ },
198
+ {
199
+ "name": "unknown-invariant-state",
200
+ "state": {
201
+ "round": 1,
202
+ "maxRounds": 7,
203
+ "invariantState": "probably",
204
+ "openFindings": 0,
205
+ "evidenceComplete": true,
206
+ "breakerLevel": 0
207
+ },
208
+ "expect": "refused",
209
+ "path": "invariantState"
210
+ },
211
+ {
212
+ "name": "missing-evidence-complete",
213
+ "state": {
214
+ "round": 1,
215
+ "maxRounds": 7,
216
+ "invariantState": "pass",
217
+ "openFindings": 0,
218
+ "breakerLevel": 0
219
+ },
220
+ "expect": "refused",
221
+ "path": "evidenceComplete"
222
+ },
223
+ {
224
+ "name": "negative-findings",
225
+ "state": {
226
+ "round": 1,
227
+ "maxRounds": 7,
228
+ "invariantState": "pass",
229
+ "openFindings": -1,
230
+ "evidenceComplete": true,
231
+ "breakerLevel": 0
232
+ },
233
+ "expect": "refused",
234
+ "path": "openFindings"
235
+ },
236
+ {
237
+ "name": "invented-key",
238
+ "state": {
239
+ "round": 1,
240
+ "maxRounds": 7,
241
+ "invariantState": "pass",
242
+ "openFindings": 0,
243
+ "evidenceComplete": true,
244
+ "breakerLevel": 0,
245
+ "confidence": 0.9
246
+ },
247
+ "expect": "refused",
248
+ "path": "",
249
+ "messageIncludes": "confidence"
250
+ }
251
+ ]
252
+ }
@@ -0,0 +1,306 @@
1
+ {
2
+ "comment": "Cross-implementation anchor for the invariant-report contract (kernel/src/invariant-report.ts): what a run may state about its own invariant checks, and how to digest one so a re-verification can cite the failure it answers. Rules a second implementation must reproduce, stated here so it need not read the TypeScript: (1) schemaVersion is exactly `iterate.invariant-report/0.1`. (2) `outcome` is `pass|fail|error`. (3) `checks` is 1..256 entries, each an object with required `name` (1..256 chars), required `kind` in `ensure|command|refused`, required `ok` boolean, and optional `detail` (<=4096); no other keys. (4) THE ONE RULE THAT MATTERS: `outcome` must follow from `checks`. `pass` requires every check to have ok true. `fail` requires at least one check with ok false. `error` is unconstrained. A report that says pass over a failed check is refused by both validators — the JSON Schema expresses this with `allOf`/`if`/`then`/`contains`, so a schema-only consumer refuses it too. (5) `kind` `refused` means the runner declined to execute a configured command because it carries shell metacharacters or is empty; it is a violation, so a report whose only failing check was refused is `fail`, never `error`. `error` is reserved for checks that could not be evaluated at all, and it produces no re-verification request. (6) `round` (>=1) and `durationMs` (>=0) are optional integers. (7) The digest is `iv_` + sha256 of the canonical JSON form: UTF-16-code-unit-sorted keys, no insignificant whitespace, arrays in order, strings as JSON escapes them; numbers use the host's shortest roundtrip form (integral values print without a fraction). (8) A re-verification request is `iterate.reverification/0.1` with `trigger.kind` exactly `invariant`, `trigger.reportDigest` matching `^iv_[0-9a-f]{64}$`, and `targets` carrying at least one of `recipeSteps` (1..64), `dimensions` (1..64 kebab-case ids <=64 chars), `operationIds` (1..64 matching `^op_[0-9A-HJKMNP-TV-Z]{26}$`); an empty target set is refused, by `anyOf` in the schema and by `superRefine` in the validator. PROVENANCE: every name, kind and detail string below was captured from `iterate_harness.defensive.invariants.check_invariants` running against the real repo — the ensure entries are the config's own `invariants.ensure` plus a file the run does not have, the command label is the real `<module>:<command>` format, the `exit 1 | ...` tail is real npm output truncated the way the runner truncates it (last three lines, joined by ' | '), and `python:ruff check src/ ; rm -rf /` is the metacharacter case the runner refuses with the exact string it uses. The runner records only violations plus a count, so the ok=true entries here are the configured check names minus the violating ones — that is how a producer derives `checks`, not an invention for this fixture.",
3
+ "input": {
4
+ "schemaVersion": "iterate.invariant-report/0.1",
5
+ "outcome": "fail",
6
+ "round": 3,
7
+ "durationMs": 917,
8
+ "checks": [
9
+ {
10
+ "name": "ensure:README.md",
11
+ "kind": "ensure",
12
+ "ok": true
13
+ },
14
+ {
15
+ "name": "ensure:iterate.config.yaml",
16
+ "kind": "ensure",
17
+ "ok": false,
18
+ "detail": "missing file: iterate.config.yaml"
19
+ },
20
+ {
21
+ "name": "typescript:npm run compile",
22
+ "kind": "command",
23
+ "ok": false,
24
+ "detail": "exit 1 | npm error To see a list of scripts, run: | npm error npm run | npm error A complete log of this run can be found in: /Users/ethanlin/.npm/_logs/2026-10-11T01_07_36_468Z-debug-0.log"
25
+ },
26
+ {
27
+ "name": "python:ruff check src/ ; rm -rf /",
28
+ "kind": "refused",
29
+ "ok": false,
30
+ "detail": "refused: unsafe command (shell metacharacter or empty)"
31
+ }
32
+ ]
33
+ },
34
+ "expectedDigest": "iv_81373b5040663b9f56a4a0bc671ab55e0d92bc33e5980b5580f3e7cec5902332",
35
+ "expectedFailingChecks": [
36
+ "ensure:iterate.config.yaml",
37
+ "typescript:npm run compile",
38
+ "python:ruff check src/ ; rm -rf /"
39
+ ],
40
+ "passInput": {
41
+ "schemaVersion": "iterate.invariant-report/0.1",
42
+ "outcome": "pass",
43
+ "round": 4,
44
+ "checks": [
45
+ {
46
+ "name": "ensure:README.md",
47
+ "kind": "ensure",
48
+ "ok": true
49
+ },
50
+ {
51
+ "name": "typescript:npm run compile",
52
+ "kind": "command",
53
+ "ok": true
54
+ }
55
+ ]
56
+ },
57
+ "passDigest": "iv_2038dfde43106446a87212196d1e6738ed4cdd9c1a90d6d55f94429401e8e501",
58
+ "errorInput": {
59
+ "schemaVersion": "iterate.invariant-report/0.1",
60
+ "outcome": "error",
61
+ "checks": [
62
+ {
63
+ "name": "python:pytest tests/ -x -q --timeout=60",
64
+ "kind": "command",
65
+ "ok": false,
66
+ "detail": "not measured: the runner could not start (timeout=60 requires pytest-timeout)"
67
+ }
68
+ ]
69
+ },
70
+ "errorDigest": "iv_7fe700d844d8c7ee60ce34220b55e6cbfca220d4aed27de0b22f091159c0c063",
71
+ "cases": [
72
+ {
73
+ "name": "pass-over-a-failed-check",
74
+ "input": {
75
+ "schemaVersion": "iterate.invariant-report/0.1",
76
+ "outcome": "pass",
77
+ "checks": [
78
+ {
79
+ "name": "ensure:README.md",
80
+ "kind": "ensure",
81
+ "ok": false,
82
+ "detail": "missing file: README.md"
83
+ }
84
+ ]
85
+ },
86
+ "expect": "refused",
87
+ "path": "outcome"
88
+ },
89
+ {
90
+ "name": "fail-with-every-check-ok",
91
+ "input": {
92
+ "schemaVersion": "iterate.invariant-report/0.1",
93
+ "outcome": "fail",
94
+ "checks": [
95
+ {
96
+ "name": "ensure:README.md",
97
+ "kind": "ensure",
98
+ "ok": true
99
+ }
100
+ ]
101
+ },
102
+ "expect": "refused",
103
+ "path": "outcome"
104
+ },
105
+ {
106
+ "name": "no-checks",
107
+ "input": {
108
+ "schemaVersion": "iterate.invariant-report/0.1",
109
+ "outcome": "pass",
110
+ "checks": []
111
+ },
112
+ "expect": "refused",
113
+ "path": "checks"
114
+ },
115
+ {
116
+ "name": "unknown-check-kind",
117
+ "input": {
118
+ "schemaVersion": "iterate.invariant-report/0.1",
119
+ "outcome": "fail",
120
+ "checks": [
121
+ {
122
+ "name": "ensure:README.md",
123
+ "kind": "vibes",
124
+ "ok": false
125
+ }
126
+ ]
127
+ },
128
+ "expect": "refused",
129
+ "path": "checks.0.kind"
130
+ },
131
+ {
132
+ "name": "check-without-ok",
133
+ "input": {
134
+ "schemaVersion": "iterate.invariant-report/0.1",
135
+ "outcome": "fail",
136
+ "checks": [
137
+ {
138
+ "name": "ensure:README.md",
139
+ "kind": "ensure",
140
+ "detail": "missing file: README.md"
141
+ }
142
+ ]
143
+ },
144
+ "expect": "refused",
145
+ "path": "checks.0.ok"
146
+ },
147
+ {
148
+ "name": "invented-outcome",
149
+ "input": {
150
+ "schemaVersion": "iterate.invariant-report/0.1",
151
+ "outcome": "probably",
152
+ "checks": [
153
+ {
154
+ "name": "ensure:README.md",
155
+ "kind": "ensure",
156
+ "ok": true
157
+ }
158
+ ]
159
+ },
160
+ "expect": "refused",
161
+ "path": "outcome"
162
+ },
163
+ {
164
+ "name": "extra-top-level-key",
165
+ "input": {
166
+ "schemaVersion": "iterate.invariant-report/0.1",
167
+ "outcome": "pass",
168
+ "checks": [
169
+ {
170
+ "name": "ensure:README.md",
171
+ "kind": "ensure",
172
+ "ok": true
173
+ }
174
+ ],
175
+ "note": "not part of the contract"
176
+ },
177
+ "expect": "refused",
178
+ "path": "",
179
+ "messageIncludes": "note"
180
+ },
181
+ {
182
+ "name": "zero-round",
183
+ "input": {
184
+ "schemaVersion": "iterate.invariant-report/0.1",
185
+ "outcome": "pass",
186
+ "round": 0,
187
+ "checks": [
188
+ {
189
+ "name": "ensure:README.md",
190
+ "kind": "ensure",
191
+ "ok": true
192
+ }
193
+ ]
194
+ },
195
+ "expect": "refused",
196
+ "path": "round"
197
+ },
198
+ {
199
+ "name": "error-report-is-accepted",
200
+ "input": {
201
+ "schemaVersion": "iterate.invariant-report/0.1",
202
+ "outcome": "error",
203
+ "checks": [
204
+ {
205
+ "name": "python:pytest tests/ -x -q --timeout=60",
206
+ "kind": "command",
207
+ "ok": false
208
+ }
209
+ ]
210
+ },
211
+ "expect": "accepted",
212
+ "digest": "iv_6d79b3b909a22c2185b11265ecf34ec04b6e7054530a96797f3dc02034ca2e2b"
213
+ },
214
+ {
215
+ "name": "refused-command-only",
216
+ "input": {
217
+ "schemaVersion": "iterate.invariant-report/0.1",
218
+ "outcome": "fail",
219
+ "checks": [
220
+ {
221
+ "name": "ensure:README.md",
222
+ "kind": "ensure",
223
+ "ok": true
224
+ },
225
+ {
226
+ "name": "python:ruff check src/ ; rm -rf /",
227
+ "kind": "refused",
228
+ "ok": false,
229
+ "detail": "refused: unsafe command (shell metacharacter or empty)"
230
+ }
231
+ ]
232
+ },
233
+ "expect": "accepted",
234
+ "failingChecks": ["python:ruff check src/ ; rm -rf /"]
235
+ }
236
+ ],
237
+ "reverificationCases": [
238
+ {
239
+ "name": "empty-targets",
240
+ "targets": {},
241
+ "expect": "refused"
242
+ },
243
+ {
244
+ "name": "dimensions-only",
245
+ "targets": {
246
+ "dimensions": ["spec-compliance", "frontend-backend"]
247
+ },
248
+ "expect": "accepted"
249
+ },
250
+ {
251
+ "name": "recipe-step-and-operation",
252
+ "targets": {
253
+ "recipeSteps": [
254
+ {
255
+ "kind": "assert",
256
+ "params": {
257
+ "selector": "id:gp-run-button"
258
+ }
259
+ }
260
+ ],
261
+ "operationIds": ["op_AAAAAAAAAAAAAAAAAAAAAAAAAA"]
262
+ },
263
+ "expect": "accepted"
264
+ },
265
+ {
266
+ "name": "uppercase-dimension",
267
+ "targets": {
268
+ "dimensions": ["Spec-Compliance"]
269
+ },
270
+ "expect": "refused"
271
+ },
272
+ {
273
+ "name": "bad-operation-id",
274
+ "targets": {
275
+ "operationIds": ["op_short"]
276
+ },
277
+ "expect": "refused"
278
+ },
279
+ {
280
+ "name": "unknown-target-kind",
281
+ "targets": {
282
+ "dimensions": ["security"],
283
+ "screenshots": ["a.png"]
284
+ },
285
+ "expect": "refused"
286
+ }
287
+ ],
288
+ "request": {
289
+ "schemaVersion": "iterate.reverification/0.1",
290
+ "trigger": {
291
+ "kind": "invariant",
292
+ "reportDigest": "iv_81373b5040663b9f56a4a0bc671ab55e0d92bc33e5980b5580f3e7cec5902332"
293
+ },
294
+ "targets": {
295
+ "recipeSteps": [
296
+ {
297
+ "kind": "assert",
298
+ "params": {
299
+ "selector": "id:gp-run-button"
300
+ }
301
+ }
302
+ ],
303
+ "dimensions": ["spec-compliance"]
304
+ }
305
+ }
306
+ }