@overkill-dev/engine 0.0.77 → 0.0.78

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 (219) hide show
  1. package/assertion-protocol/evaluation.d.ts +32 -0
  2. package/assertion-protocol/evaluation.d.ts.map +1 -0
  3. package/assertion-protocol/source-location.d.ts.map +1 -1
  4. package/assertion-protocol/source-location.js +4 -0
  5. package/assertion-protocol/source-location.js.map +1 -1
  6. package/compare/serialization-context.js +23 -0
  7. package/compare/serialization-context.js.map +1 -0
  8. package/compare/serialized-value-schema.d.ts +11 -0
  9. package/compare/serialized-value-schema.d.ts.map +1 -0
  10. package/compare/serialized-value-schema.js +76 -0
  11. package/compare/serialized-value-schema.js.map +1 -0
  12. package/compare/serialized-value-shape.d.ts +1 -0
  13. package/compare/serialized-value-shape.d.ts.map +1 -1
  14. package/compare/serialized-value.d.ts.map +1 -1
  15. package/compare/serialized-value.js +2 -1
  16. package/compare/serialized-value.js.map +1 -1
  17. package/engine/artifact-schema.d.ts +191 -0
  18. package/engine/artifact-schema.d.ts.map +1 -0
  19. package/engine/artifact-schema.js +34 -0
  20. package/engine/artifact-schema.js.map +1 -0
  21. package/engine/assertion-recorder.d.ts.map +1 -1
  22. package/engine/assertion-recorder.js +5 -0
  23. package/engine/assertion-recorder.js.map +1 -1
  24. package/engine/assertion-result-schema.d.ts +4 -0
  25. package/engine/assertion-result-schema.d.ts.map +1 -0
  26. package/engine/assertion-result-schema.js +71 -0
  27. package/engine/assertion-result-schema.js.map +1 -0
  28. package/engine/benchmark-calibration-plan.d.ts +6 -0
  29. package/engine/benchmark-calibration-plan.d.ts.map +1 -0
  30. package/engine/benchmark-calibration-plan.js +31 -0
  31. package/engine/benchmark-calibration-plan.js.map +1 -0
  32. package/engine/case-attempt-execution.js +18 -5
  33. package/engine/case-attempt-execution.js.map +1 -1
  34. package/engine/case-body-execution.js +12 -0
  35. package/engine/case-body-execution.js.map +1 -1
  36. package/engine/case-interruption.d.ts.map +1 -1
  37. package/engine/case-interruption.js +5 -1
  38. package/engine/case-interruption.js.map +1 -1
  39. package/engine/coverage-artifact.d.ts +2 -1
  40. package/engine/coverage-artifact.d.ts.map +1 -1
  41. package/engine/diff-schema.js +78 -0
  42. package/engine/diff-schema.js.map +1 -0
  43. package/engine/engine.d.ts +12 -3
  44. package/engine/engine.d.ts.map +1 -1
  45. package/engine/engine.js +66 -5
  46. package/engine/engine.js.map +1 -1
  47. package/engine/execution-error-ownership.js.map +1 -1
  48. package/engine/execution-global-error-observer.d.ts +2 -1
  49. package/engine/execution-global-error-observer.d.ts.map +1 -1
  50. package/engine/execution-global-error-observer.js +26 -5
  51. package/engine/execution-global-error-observer.js.map +1 -1
  52. package/engine/execution-observation.d.ts +12 -1
  53. package/engine/execution-observation.d.ts.map +1 -1
  54. package/engine/execution-observation.js +56 -0
  55. package/engine/execution-observation.js.map +1 -1
  56. package/engine/execution-options.d.ts +9 -4
  57. package/engine/execution-options.d.ts.map +1 -1
  58. package/engine/execution-options.js +18 -0
  59. package/engine/execution-options.js.map +1 -1
  60. package/engine/execution-preparation.js +4 -2
  61. package/engine/execution-preparation.js.map +1 -1
  62. package/engine/execution-process-budget-breach.js +18 -0
  63. package/engine/execution-process-budget-breach.js.map +1 -1
  64. package/engine/execution-process-budget-tracking.js.map +1 -1
  65. package/engine/execution-process-tracked-cases.js.map +1 -1
  66. package/engine/execution-result.d.ts.map +1 -1
  67. package/engine/execution-result.js +2 -1
  68. package/engine/execution-result.js.map +1 -1
  69. package/engine/execution-supervision-state.js +46 -1
  70. package/engine/execution-supervision-state.js.map +1 -1
  71. package/engine/execution-supervision.d.ts.map +1 -1
  72. package/engine/execution-supervision.js +38 -46
  73. package/engine/execution-supervision.js.map +1 -1
  74. package/engine/execution-test-plan-cases.js +8 -3
  75. package/engine/execution-test-plan-cases.js.map +1 -1
  76. package/engine/execution-test-plan-process-usage.js +17 -2
  77. package/engine/execution-test-plan-process-usage.js.map +1 -1
  78. package/engine/execution.d.ts +8 -2
  79. package/engine/execution.d.ts.map +1 -1
  80. package/engine/execution.js +77 -11
  81. package/engine/execution.js.map +1 -1
  82. package/engine/failure-artifact-policy.d.ts +42 -0
  83. package/engine/failure-artifact-policy.d.ts.map +1 -0
  84. package/engine/failure-artifact-policy.js +22 -0
  85. package/engine/failure-artifact-policy.js.map +1 -0
  86. package/engine/family-completion.js +11 -0
  87. package/engine/family-completion.js.map +1 -0
  88. package/engine/family-evidence-schema.js +44 -0
  89. package/engine/family-evidence-schema.js.map +1 -0
  90. package/engine/family-evidence-state.js +125 -0
  91. package/engine/family-evidence-state.js.map +1 -0
  92. package/engine/family-evidence.js +179 -0
  93. package/engine/family-evidence.js.map +1 -0
  94. package/engine/family-execution.js +41 -0
  95. package/engine/family-execution.js.map +1 -0
  96. package/engine/family-lifetime.d.ts +11 -0
  97. package/engine/family-lifetime.d.ts.map +1 -0
  98. package/engine/family-lifetime.js +72 -0
  99. package/engine/family-lifetime.js.map +1 -0
  100. package/engine/family-run.d.ts +63 -0
  101. package/engine/family-run.d.ts.map +1 -0
  102. package/engine/family-run.js +260 -0
  103. package/engine/family-run.js.map +1 -0
  104. package/engine/identity-schema.d.ts +73 -2
  105. package/engine/identity-schema.d.ts.map +1 -1
  106. package/engine/identity-schema.js +21 -2
  107. package/engine/identity-schema.js.map +1 -1
  108. package/engine/identity.d.ts +7 -0
  109. package/engine/identity.d.ts.map +1 -1
  110. package/engine/identity.js +13 -0
  111. package/engine/identity.js.map +1 -1
  112. package/engine/plan-collection-policy.d.ts +10 -0
  113. package/engine/plan-collection-policy.d.ts.map +1 -0
  114. package/engine/plan-collection-policy.js +15 -0
  115. package/engine/plan-collection-policy.js.map +1 -0
  116. package/engine/process-usage.d.ts +6 -0
  117. package/engine/process-usage.d.ts.map +1 -1
  118. package/engine/property-failure.d.ts.map +1 -1
  119. package/engine/property-failure.js +1 -0
  120. package/engine/property-failure.js.map +1 -1
  121. package/engine/property-inconclusive.d.ts +6 -0
  122. package/engine/property-inconclusive.d.ts.map +1 -0
  123. package/engine/property-inconclusive.js +20 -0
  124. package/engine/property-inconclusive.js.map +1 -0
  125. package/engine/property-plan.d.ts +8 -0
  126. package/engine/property-plan.d.ts.map +1 -0
  127. package/engine/property-plan.js +62 -0
  128. package/engine/property-plan.js.map +1 -0
  129. package/engine/property-policy.d.ts +45 -0
  130. package/engine/property-policy.d.ts.map +1 -0
  131. package/engine/property-policy.js +54 -0
  132. package/engine/property-policy.js.map +1 -0
  133. package/engine/property-trial.d.ts.map +1 -1
  134. package/engine/property-trial.js +1 -1
  135. package/engine/property-trial.js.map +1 -1
  136. package/engine/reporter-dispatcher.d.ts.map +1 -1
  137. package/engine/reporter-dispatcher.js +4 -17
  138. package/engine/reporter-dispatcher.js.map +1 -1
  139. package/engine/reporter.d.ts +5 -1
  140. package/engine/reporter.d.ts.map +1 -1
  141. package/engine/reporter.js.map +1 -1
  142. package/engine/reporting-context.d.ts +12 -1
  143. package/engine/reporting-context.d.ts.map +1 -1
  144. package/engine/reporting-context.js +44 -0
  145. package/engine/reporting-context.js.map +1 -1
  146. package/engine/run-artifact.d.ts +84 -2
  147. package/engine/run-artifact.d.ts.map +1 -1
  148. package/engine/run-artifact.js +88 -0
  149. package/engine/run-artifact.js.map +1 -0
  150. package/engine/run-result.d.ts +7 -3
  151. package/engine/run-result.d.ts.map +1 -1
  152. package/engine/run-result.js +4 -1
  153. package/engine/run-result.js.map +1 -1
  154. package/engine/runner-error-schema.d.ts +4 -0
  155. package/engine/runner-error-schema.d.ts.map +1 -0
  156. package/engine/runner-error-schema.js +29 -0
  157. package/engine/runner-error-schema.js.map +1 -0
  158. package/engine/runtime-attachment.js +7 -0
  159. package/engine/runtime-attachment.js.map +1 -0
  160. package/engine/runtime-matrix-expansion.d.ts +3 -0
  161. package/engine/runtime-matrix-expansion.d.ts.map +1 -0
  162. package/engine/runtime-matrix-expansion.js +150 -0
  163. package/engine/runtime-matrix-expansion.js.map +1 -0
  164. package/engine/standard-engine.js +1 -0
  165. package/engine/standard-engine.js.map +1 -1
  166. package/engine/test-body.d.ts +20 -3
  167. package/engine/test-body.d.ts.map +1 -1
  168. package/engine/test-body.js +50 -3
  169. package/engine/test-body.js.map +1 -1
  170. package/engine/test-control-error.d.ts +2 -0
  171. package/engine/test-control-error.d.ts.map +1 -0
  172. package/engine/test-control-error.js +10 -0
  173. package/engine/test-control-error.js.map +1 -0
  174. package/engine/test-data.d.ts +0 -1
  175. package/engine/test-data.d.ts.map +1 -1
  176. package/engine/test-data.js.map +1 -1
  177. package/engine/test-debug-artifact.js +166 -0
  178. package/engine/test-debug-artifact.js.map +1 -0
  179. package/engine/test-debug-context.js +120 -0
  180. package/engine/test-debug-context.js.map +1 -0
  181. package/engine/test-debug-providers.js +68 -0
  182. package/engine/test-debug-providers.js.map +1 -0
  183. package/engine/test-debug-recording.js +249 -0
  184. package/engine/test-debug-recording.js.map +1 -0
  185. package/engine/test-debug.d.ts +285 -0
  186. package/engine/test-debug.d.ts.map +1 -0
  187. package/engine/test-debug.js +67 -0
  188. package/engine/test-debug.js.map +1 -0
  189. package/engine/test-family.d.ts +112 -0
  190. package/engine/test-family.d.ts.map +1 -0
  191. package/engine/test-family.js +165 -0
  192. package/engine/test-family.js.map +1 -0
  193. package/engine/test-node.d.ts +11 -8
  194. package/engine/test-node.d.ts.map +1 -1
  195. package/engine/test-node.js +7 -2
  196. package/engine/test-node.js.map +1 -1
  197. package/engine/test-plan-locations.js +21 -0
  198. package/engine/test-plan-locations.js.map +1 -0
  199. package/engine/test-plan.d.ts +5 -3
  200. package/engine/test-plan.d.ts.map +1 -1
  201. package/engine/test-plan.js +19 -4
  202. package/engine/test-plan.js.map +1 -1
  203. package/engine/test-scope-lifecycle.js +3 -0
  204. package/engine/test-scope-lifecycle.js.map +1 -1
  205. package/engine/test-scope.d.ts +3 -0
  206. package/engine/test-scope.d.ts.map +1 -1
  207. package/module-loading-scope.d.ts +8 -0
  208. package/module-loading-scope.d.ts.map +1 -0
  209. package/module-loading-scope.js +23 -0
  210. package/module-loading-scope.js.map +1 -0
  211. package/package.json +83 -4
  212. package/packages/engine/engine.entry-point.d.ts +26 -25
  213. package/packages/engine/engine.entry-point.d.ts.map +1 -1
  214. package/packages/engine/engine.entry-point.js +12 -11
  215. package/packages/engine/engine.entry-point.js.map +1 -1
  216. package/readme.md +83 -1
  217. package/software-bill-of-materials.cyclonedx.json +4 -4
  218. package/engine/execution-process-budget-breach.d.ts +0 -8
  219. package/engine/execution-process-budget-breach.d.ts.map +0 -1
package/readme.md CHANGED
@@ -20,6 +20,9 @@ Top-level API:
20
20
  - `createTable(options)`
21
21
  - `createTestPlan(root)`
22
22
  - `execute(testPlan)`
23
+ - `defineTestFamily(definition)`
24
+ - `prepareFamily(request)`
25
+ - `execute(collectedFamilyRun, options)`
23
26
  - `createEngine()`
24
27
  - `formatCaseId(caseId)`
25
28
  - `workIdentityKey(workId)`
@@ -38,7 +41,7 @@ Top-level API:
38
41
  - `RequireAssertionFacade`, `FailedCheck`, `TestFailure`, `RunnerError`
39
42
  - `Diff`, `DiffPathSegment`, `SerializedValue`, `SerializationBudget`
40
43
  - `TestAnnotations`, `TestAnnotationsInput`, `TestControls`, `TestControlsInput`
41
- - `TestFamily`, `CaptureMode`
44
+ - `TestFamilyId`, `CaptureMode`
42
45
 
43
46
  The top-level constructors share one default engine instance, including
44
47
  installed package copies in the same process. Use
@@ -285,3 +288,82 @@ Property invocation evidence includes a nullable `summary` with phase accounting
285
288
  seeds, input coverage, and exhaustive traversal state. `original` and `retained`
286
289
  observations are jointly present or jointly null. Progress snapshots use the same
287
290
  shape as final case and attempt results; historical summaries may be unavailable.
291
+
292
+ ## Family Definitions
293
+
294
+ `defineTestFamily` creates a branded `TestFamily<Settings>` with an implementation
295
+ ID/version, explicit module reference (or `null` for local use), supported
296
+ features, a settings parser, and a lazy backend loader. Importing or inspecting a
297
+ definition does not load its backend. Definitions do not register global state.
298
+
299
+ `parseSettings` returns a deeply frozen JSON copy. Unsupported values and cycles
300
+ are rejected; nested containers use the shared JSON snapshot depth limit of 64.
301
+ `TestFamilyId` is the stable string stored in plans and results.
302
+
303
+ Executable work, work units, and artifacts carry a nullable `familyVariant`.
304
+ Non-null variants distinguish implementations' executable targets while retaining
305
+ logical case identity. Neutral variants preserve existing identity keys.
306
+
307
+ ## Failure artifact policy
308
+
309
+ `execute` accepts `failureArtifacts` with captured-output, assertion serialization,
310
+ and human rendering limits. Omission uses `defaultFailureArtifactPolicy`.
311
+ Concurrent and nested executions keep their serialization budgets isolated;
312
+ diagnostic policy does not change collected test identity.
313
+
314
+ Reporter contexts from older runners may omit `failureArtifacts`. Rendering then
315
+ uses the active execution policy or its defaults.
316
+
317
+ `RunArtifact` includes `WorkerCrashArtifact` and `ProcessExhaustionArtifact`.
318
+ They preserve active `WorkId` and `AttemptId` evidence, unavailable metadata as
319
+ `null`, and capture provenance. Case-owned artifacts accompany `test-end`;
320
+ run-scoped artifacts accompany the final result. These variants need no
321
+ attachment backend or standalone files. Existing runner-error classifications
322
+ and case verdicts remain authoritative.
323
+
324
+ ### Debug diagnostics
325
+
326
+ Supplied execution options require `debug: { mode: 'off' }`,
327
+ `debug: { mode: 'all' }`, or `debug: { mode: 'selected', work: [...] }`.
328
+ Calling `execute(plan)` keeps debug recording off. Selected identities never
329
+ change which tests execute.
330
+
331
+ Both test scopes expose `scope.debug.includeRecording({ name, recorded })`.
332
+ The callback returns application-owned event arrays and is never invoked when
333
+ debug is off. Provider failures are artifact runner errors; case verdicts remain
334
+ intact.
335
+
336
+ `TestDebugArtifact` is a typed, JSON-safe result artifact. Measurements identify
337
+ shared observation windows and sampling limits. Incomplete `debug-checkpoint`
338
+ events are diagnostic progress; completed evidence appears in `test-end.artifacts`
339
+ and `RunResult.artifacts`. Direct engine execution keeps this evidence in memory.
340
+
341
+ ## Direct family execution
342
+
343
+ Use an engine-created plan, an explicit family definition, and an absolute
344
+ project root. Select work by its prepared identity. The engine rejects empty,
345
+ unknown, or duplicate selections. Authored skips remain in the result.
346
+
347
+ ```ts
348
+ await using prepared = await engine.prepareFamily({
349
+ testPlan,
350
+ testFamily,
351
+ settings,
352
+ projectRoot,
353
+ signal
354
+ });
355
+ const collected = await prepared.collect({
356
+ workIds: prepared.testPlan.cases.map((testCase) => testCase.workId),
357
+ signal
358
+ });
359
+ const result = await engine.execute(collected, { ...executionOptions, signal });
360
+ ```
361
+
362
+ Preparations are single-use: collect once and execute once. Failed collection
363
+ closes the preparation. Execution disposes family resources before final delivery;
364
+ cleanup failures remain in the failed result. Explicit disposal cancels and awaits
365
+ active work, and is a no-op after engine cleanup. Prepare again for each rerun.
366
+
367
+ Runtime families use ordinary body execution. Analysis families supply evidence
368
+ through the engine and never invoke test bodies. Both use the same reporters.
369
+ The top-level functions use the default engine.
@@ -16,9 +16,9 @@
16
16
  "component": {
17
17
  "type": "library",
18
18
  "name": "@overkill-dev/engine",
19
- "version": "0.0.77",
20
- "bom-ref": "pkg:npm/@overkill-dev/engine@0.0.77",
21
- "purl": "pkg:npm/@overkill-dev/engine@0.0.77"
19
+ "version": "0.0.78",
20
+ "bom-ref": "pkg:npm/@overkill-dev/engine@0.0.78",
21
+ "purl": "pkg:npm/@overkill-dev/engine@0.0.78"
22
22
  }
23
23
  },
24
24
  "components": [
@@ -106,7 +106,7 @@
106
106
  "ref": "pkg:npm/@enormora/clock@0.0.3"
107
107
  },
108
108
  {
109
- "ref": "pkg:npm/@overkill-dev/engine@0.0.77",
109
+ "ref": "pkg:npm/@overkill-dev/engine@0.0.78",
110
110
  "dependsOn": [
111
111
  "pkg:npm/@enormora/clock@0.0.3",
112
112
  "pkg:npm/diff@9.0.0",
@@ -1,8 +0,0 @@
1
- export type ExecuteProcessBudgets = {
2
- readonly activeResourceCount: number | null;
3
- readonly javaScriptEngineHeapBytes: number | null;
4
- readonly residentSetBytes: number | null;
5
- readonly residentSetGrowthBytesPerSecond: number | null;
6
- };
7
- export {};
8
- //# sourceMappingURL=execution-process-budget-breach.d.ts.map
@@ -1 +0,0 @@
1
- {"version":3,"file":"execution-process-budget-breach.d.ts","sourceRoot":"","sources":["../../../../source/engine/execution-process-budget-breach.ts"],"names":[],"mappings":"MAGM,MAAM,qBAAqB,GAAG;IAChC,QAAQ,CAAC,mBAAmB,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5C,QAAQ,CAAC,yBAAyB,EAAE,MAAM,GAAG,IAAI,CAAC;IAClD,QAAQ,CAAC,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;IACzC,QAAQ,CAAC,+BAA+B,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3D,CAAC;MAII,CAA4B,EAKjC,CAAC"}