geospec 0.1.0-beta.7 → 0.1.0-beta.9

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 (80) hide show
  1. package/README.md +41 -8
  2. package/agent/geospec-authoring/SKILL.md +12 -11
  3. package/agent/geospec-authoring/api-functions.md +1 -16
  4. package/agent/geospec-authoring/api-index.md +53 -46
  5. package/agent/geospec-authoring/api-types-2.md +85 -0
  6. package/agent/geospec-authoring/api-types.md +189 -251
  7. package/agent/geospec-authoring/public-api-functions.md +71 -23
  8. package/agent/geospec-authoring/public-api-index.md +243 -191
  9. package/agent/geospec-authoring/public-api-types-2.md +295 -401
  10. package/agent/geospec-authoring/public-api-types-3.md +412 -119
  11. package/agent/geospec-authoring/public-api-types.md +237 -126
  12. package/agent/resources.js +13 -12
  13. package/agent/skills.json +3 -2
  14. package/dist/assertion-client/client.d.mts +3 -1
  15. package/dist/cli/cli.d.mts +48 -0
  16. package/dist/cli/cli.mjs +30 -0
  17. package/dist/cli/index.d.mts +3 -0
  18. package/dist/cli/index.mjs +1 -0
  19. package/dist/cli/main.d.mts +1 -0
  20. package/dist/cli/main.mjs +2 -0
  21. package/dist/cli/node-host.d.mts +26 -0
  22. package/dist/cli/node-host.mjs +1 -0
  23. package/dist/cli/wire-value.mjs +1 -0
  24. package/dist/config/define-config.d.mts +15 -0
  25. package/dist/config/define-config.mjs +2 -0
  26. package/dist/config/index.d.mts +4 -3
  27. package/dist/config/index.mjs +1 -1
  28. package/dist/config/node/load.d.mts +2 -1
  29. package/dist/config/node/load.mjs +1 -1
  30. package/dist/config/read-geospec-config.d.mts +47 -0
  31. package/dist/config/read-geospec-config.mjs +3 -0
  32. package/dist/config/types.d.mts +11 -25
  33. package/dist/config/validate.mjs +1 -1
  34. package/dist/engine/client.d.mts +3 -1
  35. package/dist/mesh/index.d.mts +2 -2
  36. package/dist/model/index.d.mts +3 -3
  37. package/dist/model/index.mjs +1 -1
  38. package/dist/model/mesh-evidence-matchers.d.mts +12 -0
  39. package/dist/model/mesh-evidence-matchers.mjs +1 -0
  40. package/dist/model/native-model-loader.d.mts +8 -8
  41. package/dist/model/native-model-loader.mjs +1 -1
  42. package/dist/model/node/command-exporter.d.mts +33 -0
  43. package/dist/model/node/command-exporter.mjs +1 -0
  44. package/dist/model/node/index.d.mts +2 -0
  45. package/dist/model/node/index.mjs +1 -0
  46. package/dist/model/types.d.mts +111 -63
  47. package/dist/runner/collector.d.mts +0 -2
  48. package/dist/runner/index.d.mts +1 -1
  49. package/dist/runner/native/index.mjs +1 -1
  50. package/dist/runner/native/native-serial-runner.mjs +1 -1
  51. package/dist/runner/node/engine.d.mts +40 -0
  52. package/dist/runner/node/engine.mjs +1 -0
  53. package/dist/runner/node/index.d.mts +5 -0
  54. package/dist/runner/node/index.mjs +1 -0
  55. package/dist/runner/node/node-vm-filesystem.d.mts +22 -0
  56. package/dist/runner/node/node-vm-filesystem.mjs +1 -0
  57. package/dist/runner/node/pool-runner.d.mts +67 -0
  58. package/dist/runner/node/pool-runner.mjs +1 -0
  59. package/dist/runner/node/pool-worker-entry.d.mts +43 -0
  60. package/dist/runner/node/pool-worker-entry.mjs +1 -0
  61. package/dist/runner/pool/events.mjs +1 -0
  62. package/dist/runner/pool/pool-messages.d.mts +2 -10
  63. package/dist/runner/pool/pool.d.mts +36 -0
  64. package/dist/runner/pool/pool.mjs +1 -0
  65. package/dist/runner/pool/shard-planner.mjs +1 -0
  66. package/dist/runner/pool/shard-timings.d.mts +36 -0
  67. package/dist/runner/pool/transport.mjs +1 -0
  68. package/dist/runner/pool/worker-host.d.mts +36 -0
  69. package/dist/runner/pool/worker-host.mjs +1 -0
  70. package/dist/runner/run-geospec-module.mjs +7 -7
  71. package/dist/runner/types.d.mts +9 -10
  72. package/dist/runner/worker/index.d.mts +5 -2
  73. package/dist/runner/worker/index.mjs +1 -1
  74. package/dist/runner/worker/runner-types.d.mts +2 -14
  75. package/dist/runner/worker/serial-runner.mjs +1 -1
  76. package/package.json +28 -5
  77. package/dist/config/tau-project-artifact.d.mts +0 -54
  78. package/dist/config/tau-project-artifact.mjs +0 -3
  79. package/dist/model/export-intent.d.mts +0 -79
  80. package/dist/model/export-intent.mjs +0 -1
@@ -1,6 +1,6 @@
1
1
  # geospec — Types (2)
2
2
 
3
- 63 top-level symbols. Signatures are verbatim typescript.
3
+ 57 top-level symbols. Signatures are verbatim typescript.
4
4
 
5
5
  // Inline code-CAD model load options
6
6
  LoadModelCodeOptions: {
@@ -12,13 +12,9 @@ LoadModelCodeOptions: {
12
12
  rootDir?: never;
13
13
  /** Geometry format to export. Defaults to `glb`. */
14
14
  format?: GeoSpecModelFormat;
15
- /** Explicit parameters passed to the runtime. */
15
+ /** Explicit parameters passed to the exporter. */
16
16
  parameters?: Record<string, unknown>;
17
- /** Runtime client or lazy runtime factory. */
18
- runtime?: GeoSpecRuntimeClient | GeoSpecRuntimeClientFactory;
19
- /** Source-specific runtime adapters, e.g. host-provided GPL-isolated kernels. */
20
- sourceAdapters?: readonly GeoSpecRuntimeSourceAdapter[];
21
- /** Project root used by runtime integrations. */
17
+ /** Absolute project root passed to the exporter. */
22
18
  projectPath?: string;
23
19
  /** STEP reader strategy used for STEP exports. */
24
20
  stepStreaming?: StepStreamingMode;
@@ -35,12 +31,11 @@ LoadModelCodeOptions: {
35
31
  */
36
32
  workUnitLimit?: number;
37
33
  /**
38
- * Axis-aligned millimetre box the kernel crops the model to before export, so a large mesh model
39
- * can be checked region by region. Only kernels whose direct GLB export declares a `region` option
40
- * honor it; any other kernel, a STEP load or a crop the kernel does not confirm refuses with a typed
41
- * diagnostic instead of loading the whole model. The cropped subject is a different subject: its
42
- * admission carries the kernel's crop notice and its load evidence records `region`, so a claim on
43
- * it never stands for the whole model.
34
+ * Axis-aligned millimetre box the exporter crops the model to before export, so a large mesh model
35
+ * can be checked region by region. Only an exporter that declares `region` honours it; any other
36
+ * exporter, or a crop the exporter cannot make, refuses with a typed diagnostic instead of loading
37
+ * the whole model. The cropped subject is a different subject: its load evidence records `region`,
38
+ * so a claim on it never stands for the whole model.
44
39
  */
45
40
  region?: GeoSpecLoadRegion;
46
41
  }
@@ -57,16 +52,10 @@ LoadModelCodeOptions: {
57
52
  // Geometry format to export
58
53
  format?: GeoSpecModelFormat
59
54
 
60
- // Explicit parameters passed to the runtime
55
+ // Explicit parameters passed to the exporter
61
56
  parameters?: Record<string, unknown>
62
57
 
63
- // Runtime client or lazy runtime factory
64
- runtime?: GeoSpecRuntimeClient | GeoSpecRuntimeClientFactory
65
-
66
- // Source-specific runtime adapters, e.g
67
- sourceAdapters?: readonly GeoSpecRuntimeSourceAdapter[]
68
-
69
- // Project root used by runtime integrations
58
+ // Absolute project root passed to the exporter
70
59
  projectPath?: string
71
60
 
72
61
  // STEP reader strategy used for STEP exports
@@ -84,7 +73,7 @@ LoadModelCodeOptions: {
84
73
  // Default work-unit budget for every claim on this subject
85
74
  workUnitLimit?: number
86
75
 
87
- // Axis-aligned millimetre box the kernel crops the model to before export, so a large mesh model can be checked region by region
76
+ // Axis-aligned millimetre box the exporter crops the model to before export, so a large mesh model can be checked region by region
88
77
  region?: GeoSpecLoadRegion
89
78
 
90
79
  // Filesystem-backed model load options
@@ -100,16 +89,12 @@ LoadModelFileOptions: {
100
89
  * evidence.
101
90
  */
102
91
  rootDir?: string;
103
- /** Project root used by runtime integrations. */
92
+ /** Absolute project root passed to the exporter. */
104
93
  projectPath?: string;
105
94
  /** Geometry format to export. Defaults to `glb`. */
106
95
  format?: GeoSpecModelFormat;
107
- /** Explicit parameters passed to the runtime. */
96
+ /** Explicit parameters passed to the exporter. */
108
97
  parameters?: Record<string, unknown>;
109
- /** Runtime client or lazy runtime factory. */
110
- runtime?: GeoSpecRuntimeClient | GeoSpecRuntimeClientFactory;
111
- /** Source-specific runtime adapters, e.g. host-provided GPL-isolated kernels. */
112
- sourceAdapters?: readonly GeoSpecRuntimeSourceAdapter[];
113
98
  /** STEP reader strategy used for STEP exports. */
114
99
  stepStreaming?: StepStreamingMode;
115
100
  /** Whether STEP loading should also produce mesh evidence. Defaults to true. */
@@ -125,12 +110,11 @@ LoadModelFileOptions: {
125
110
  */
126
111
  workUnitLimit?: number;
127
112
  /**
128
- * Axis-aligned millimetre box the kernel crops the model to before export, so a large mesh model
129
- * can be checked region by region. Only kernels whose direct GLB export declares a `region` option
130
- * honor it; any other kernel, a STEP load or a crop the kernel does not confirm refuses with a typed
131
- * diagnostic instead of loading the whole model. The cropped subject is a different subject: its
132
- * admission carries the kernel's crop notice and its load evidence records `region`, so a claim on
133
- * it never stands for the whole model.
113
+ * Axis-aligned millimetre box the exporter crops the model to before export, so a large mesh model
114
+ * can be checked region by region. Only an exporter that declares `region` honours it; any other
115
+ * exporter, or a crop the exporter cannot make, refuses with a typed diagnostic instead of loading
116
+ * the whole model. The cropped subject is a different subject: its load evidence records `region`,
117
+ * so a claim on it never stands for the whole model.
134
118
  */
135
119
  region?: GeoSpecLoadRegion;
136
120
  }
@@ -141,21 +125,15 @@ LoadModelFileOptions: {
141
125
  // Project-relative folder `file` resolves in, for a suite that loads from somewhere other than the project root
142
126
  rootDir?: string
143
127
 
144
- // Project root used by runtime integrations
128
+ // Absolute project root passed to the exporter
145
129
  projectPath?: string
146
130
 
147
131
  // Geometry format to export
148
132
  format?: GeoSpecModelFormat
149
133
 
150
- // Explicit parameters passed to the runtime
134
+ // Explicit parameters passed to the exporter
151
135
  parameters?: Record<string, unknown>
152
136
 
153
- // Runtime client or lazy runtime factory
154
- runtime?: GeoSpecRuntimeClient | GeoSpecRuntimeClientFactory
155
-
156
- // Source-specific runtime adapters, e.g
157
- sourceAdapters?: readonly GeoSpecRuntimeSourceAdapter[]
158
-
159
137
  // STEP reader strategy used for STEP exports
160
138
  stepStreaming?: StepStreamingMode
161
139
 
@@ -171,7 +149,7 @@ LoadModelFileOptions: {
171
149
  // Default work-unit budget for every claim on this subject
172
150
  workUnitLimit?: number
173
151
 
174
- // Axis-aligned millimetre box the kernel crops the model to before export, so a large mesh model can be checked region by region
152
+ // Axis-aligned millimetre box the exporter crops the model to before export, so a large mesh model can be checked region by region
175
153
  region?: GeoSpecLoadRegion
176
154
 
177
155
  // Options accepted by {@link import ('./load-model.js').loadModel}
@@ -183,7 +161,7 @@ LoadModelOptions: LoadModelSourceOptions | LoadModelCodeOptions<Code> | LoadMode
183
161
  // Geometry format to export
184
162
  format?: GeoSpecModelFormat
185
163
 
186
- // Explicit parameters passed to the runtime
164
+ // Explicit parameters passed to the exporter
187
165
  parameters?: Record<string, unknown>
188
166
 
189
167
  // STEP reader strategy used for STEP exports
@@ -283,6 +261,43 @@ LoadModelSourceOptions: {
283
261
  // Default work-unit budget for every claim on this subject
284
262
  workUnitLimit?: number
285
263
 
264
+ // Options for {@link commandExporter}
265
+ CommandExporterOptions: {
266
+ readonly id: string;
267
+ /** File extensions without the dot, or `'*'`. */
268
+ readonly extensions: readonly string[];
269
+ /** Executable and leading arguments, such as `['python', 'export.py']`. */
270
+ readonly command: readonly string[];
271
+ /** What the command can do. Protocol 1 carries no inline sources, so `inlineSources` must not be set. */
272
+ readonly capabilities: GeoSpecExporterCapabilities;
273
+ /** Working directory of the command; defaults to the request's project root. */
274
+ readonly cwd?: string;
275
+ /** Extra environment variables, merged over this process's. */
276
+ readonly env?: Readonly<Record<string, string>>;
277
+ /** Positive milliseconds one export may run before the command is killed and the export fails. */
278
+ readonly exportTimeout?: number;
279
+ }
280
+
281
+ readonly id: string
282
+
283
+ // File extensions without the dot, or `'*'`
284
+ readonly extensions: readonly string[]
285
+
286
+ // Executable and leading arguments, such as `['python', 'export.py']`
287
+ readonly command: readonly string[]
288
+
289
+ // What the command can do
290
+ readonly capabilities: GeoSpecExporterCapabilities
291
+
292
+ // Working directory of the command
293
+ readonly cwd?: string
294
+
295
+ // Extra environment variables, merged over this process's
296
+ readonly env?: Readonly<Record<string, string>>
297
+
298
+ // Positive milliseconds one export may run before the command is killed and the export fails
299
+ readonly exportTimeout?: number
300
+
286
301
  // Collects suites, tests, assertions, and async completion state for one GeoSpec module execution
287
302
  GeoSpecCollector: {
288
303
  tests: GeoSpecTestCase[];
@@ -316,17 +331,11 @@ GeoSpecCollector: {
316
331
 
317
332
  // Per-module collector configuration
318
333
  GeoSpecCollectorOptions: {
319
- matcherWallBackstop?: number;
320
- forensic?: boolean;
321
334
  nativeAssertions: GeoSpecAssertionClientOptions;
322
335
  /** Observes each selected test as it starts and settles, for host progress reporting. */
323
336
  onTestEvent?: (event: GeoSpecTestEvent) => void;
324
337
  }
325
338
 
326
- matcherWallBackstop?: number
327
-
328
- forensic?: boolean
329
-
330
339
  nativeAssertions: GeoSpecAssertionClientOptions
331
340
 
332
341
  // Observes each selected test as it starts and settles, for host progress reporting
@@ -538,10 +547,6 @@ RunGeoSpecModuleOptions: {
538
547
  testNamePattern?: string | RegExp;
539
548
  /** Timeout for async test callbacks, in milliseconds. */
540
549
  testTimeout?: number;
541
- /** Milliseconds. Non-verdict matcher infrastructure backstop. */
542
- matcherWallBackstop?: number;
543
- /** Emit structured forensic events for this run. */
544
- forensic?: boolean;
545
550
  /** Observes each selected test as it starts and settles, for host progress reporting. */
546
551
  onTestEvent?: (event: GeoSpecTestEvent) => void;
547
552
  /**
@@ -579,12 +584,6 @@ RunGeoSpecModuleOptions: {
579
584
  // Timeout for async test callbacks, in milliseconds
580
585
  testTimeout?: number
581
586
 
582
- // Milliseconds
583
- matcherWallBackstop?: number
584
-
585
- // Emit structured forensic events for this run
586
- forensic?: boolean
587
-
588
587
  // Observes each selected test as it starts and settles, for host progress reporting
589
588
  onTestEvent?: (event: GeoSpecTestEvent) => void
590
589
 
@@ -655,8 +654,8 @@ CreateGeoSpecNativeModelLoaderOptions: {
655
654
  readonly format?: Extract<GeoSpecModelFormat, 'glb' | 'step' | 'stp'>;
656
655
  readonly projectPath?: string;
657
656
  readonly readSource?: GeoSpecNativeSourceReader;
658
- readonly runtime?: GeoSpecRuntimeClient | GeoSpecRuntimeClientFactory;
659
- readonly sourceAdapters?: readonly GeoSpecRuntimeSourceAdapter[];
657
+ /** Model exporters for source-kind files; the first whose `extensions` claim the file exports it. */
658
+ readonly exporters?: readonly GeoSpecModelExporter[];
660
659
  /**
661
660
  * Subject handles carried between the release scopes of loaders that share one engine, keyed by
662
661
  * subjectHash. With a carrier, `releaseAll` keeps this scope's subjects for the next scope and
@@ -680,9 +679,8 @@ CreateGeoSpecNativeModelLoaderOptions: {
680
679
 
681
680
  readonly readSource?: GeoSpecNativeSourceReader
682
681
 
683
- readonly runtime?: GeoSpecRuntimeClient | GeoSpecRuntimeClientFactory
684
-
685
- readonly sourceAdapters?: readonly GeoSpecRuntimeSourceAdapter[]
682
+ // Model exporters for source-kind files
683
+ readonly exporters?: readonly GeoSpecModelExporter[]
686
684
 
687
685
  // Subject handles carried between the release scopes of loaders that share one engine, keyed by subjectHash
688
686
  readonly carried?: Map<string, unknown>
@@ -704,7 +702,7 @@ GeoSpecNativeLoadModelOptions: LoadModelOptions<Code> & {
704
702
  // Geometry format to export
705
703
  format?: GeoSpecModelFormat
706
704
 
707
- // Explicit parameters passed to the runtime
705
+ // Explicit parameters passed to the exporter
708
706
  parameters?: Record<string, unknown>
709
707
 
710
708
  // STEP reader strategy used for STEP exports
@@ -751,7 +749,7 @@ GeoSpecNativeModelEngine: GeoSpecNativeEngine & {
751
749
  releaseSubject(request: Uint8Array<ArrayBuffer>): Uint8Array<ArrayBuffer>;
752
750
 
753
751
  // Model loader injected into native VM runs
754
- // Remarks: Direct `source` loads read their source again on every call and the engine digests those exact bytes; bytes equal to an admitted subject's reuse that subject by digest, length and descriptor, and edited bytes admit a new subject. Runtime loads are coalesced per release scope (one run): a load whose file, inline code, project path, parameters, format, tolerances, region and ingest options equal an earlier successful load's reuses that admission without exporting or ingesting again. A file load is reused only while a Runtime source snapshot still matches the earlier load's complete source revision; otherwise, or when every owner of the earlier admission has released it, the load exports afresh. Failures are never reused.
752
+ // Remarks: Direct `source` loads read their source again on every call and the engine digests those exact bytes; bytes equal to an admitted subject's reuse that subject by digest, length and descriptor, and edited bytes admit a new subject. Exported loads are coalesced per release scope (one run): a load whose file, inline code, project path, parameters, format, tolerances, region and ingest options equal an earlier successful load's reuses that admission without exporting or ingesting again. A file load is reused only while the exporter's `revision` still matches the earlier load's complete source revision; otherwise, or when every owner of the earlier admission has released it, the load exports afresh. Failures are never reused.
755
753
  GeoSpecNativeModelLoader: <Code extends Record<string, string> = Record<string, string>>(options: GeoSpecNativeLoadModelOptions<Code>) => Promise<GeoSpecNativeModelSubject>
756
754
 
757
755
  // Subject identity returned by native STEP/GLB admission
@@ -787,7 +785,7 @@ ManagedGeoSpecNativeModelLoader: GeoSpecNativeModelLoader & {
787
785
  /**
788
786
  * Drain registered admissions, including additions while drainage awaits,
789
787
  * then release this scope's subjects (with a carrier: the previous scope's
790
- * subjects this scope did not load again) and owned Runtime clients.
788
+ * subjects this scope did not load again), then close every exporter it exported through.
791
789
  *
792
790
  * Await the intended complete load chain before final release, and await
793
791
  * this method before closing the caller-owned engine. Calls after it returns
@@ -804,6 +802,106 @@ ManagedGeoSpecNativeModelLoader: GeoSpecNativeModelLoader & {
804
802
  // ManagedGeoSpecNativeModelLoader.releaseAll (method)
805
803
  releaseAll(): Promise<void>;
806
804
 
805
+ // Options for {@link createNodeGeoSpecEngine}
806
+ CreateNodeGeoSpecEngineOptions: {
807
+ /** Caller-inclusive CPU permits for the native addon; the WASM build is single-threaded and ignores them. */
808
+ readonly executionPermits?: number;
809
+ }
810
+
811
+ // Caller-inclusive CPU permits for the native addon
812
+ readonly executionPermits?: number
813
+
814
+ // Which build of `geospec-engine` a Node engine runs on
815
+ GeoSpecEngineBinding: 'napi' | 'wasm'
816
+
817
+ // An engine and the build it runs on
818
+ NodeGeoSpecEngine: {
819
+ readonly engine: GeoSpecNativeModelEngine & {
820
+ close(): void;
821
+ };
822
+ readonly binding: GeoSpecEngineBinding;
823
+ }
824
+
825
+ readonly engine: GeoSpecNativeModelEngine & {
826
+ close(): void;
827
+ }
828
+
829
+ readonly binding: GeoSpecEngineBinding
830
+
831
+ // Options for the Node pool
832
+ GeoSpecNodePoolOptions: {
833
+ /** Absolute project root. */
834
+ projectPath: string;
835
+ /** The `geospec.config.*` each worker imports for its exporters; absent to discover one in `projectPath`. */
836
+ configPath?: string;
837
+ /**
838
+ * URLs of modules each worker imports whose default export creates exporters that precede the config's (see
839
+ * `GeoSpecExporterModule`). A host that composes its own exporters, such as `tau test`, passes them here.
840
+ */
841
+ exporterModules?: readonly string[];
842
+ /** Number of outer worker isolates; defaults to one. */
843
+ workers?: number;
844
+ /**
845
+ * Caller-inclusive total CPU budget; defaults to one per worker. Above one
846
+ * permit per worker only with a single worker: every worker shares this
847
+ * process's OCCT library, whose admission refuses any second engine beside
848
+ * one holding two or more permits.
849
+ */
850
+ budget?: number;
851
+ /** Non-verdict shard watchdog in milliseconds. */
852
+ shardTimeout?: number;
853
+ }
854
+
855
+ // Absolute project root
856
+ projectPath: string
857
+
858
+ // The `geospec.config.*` each worker imports for its exporters
859
+ configPath?: string
860
+
861
+ // URLs of modules each worker imports whose default export creates exporters that precede the config's (see `GeoSpecExporterModule`)
862
+ exporterModules?: readonly string[]
863
+
864
+ // Number of outer worker isolates
865
+ workers?: number
866
+
867
+ // Caller-inclusive total CPU budget
868
+ budget?: number
869
+
870
+ // Non-verdict shard watchdog in milliseconds
871
+ shardTimeout?: number
872
+
873
+ // The slice of `node:worker_threads`' `Worker` the pool drives
874
+ // Remarks: Declared structurally so the adapter can be exercised against a stub as well as against a real thread (D-8: vitest cannot host a TypeScript worker).
875
+ NodeWorkerLike: {
876
+ postMessage(value: unknown): void;
877
+ on(event: 'message', listener: (value: GeoSpecPoolWorkerMessage) => void): void;
878
+ on(event: 'exit', listener: (code: number) => void): void;
879
+ on(event: 'error', listener: (error: Error) => void): void;
880
+ terminate(): Promise<number> | number;
881
+ }
882
+
883
+ // NodeWorkerLike.postMessage (method)
884
+ postMessage(value: unknown): void;
885
+
886
+ // NodeWorkerLike.on (method)
887
+ on(event: 'message', listener: (value: GeoSpecPoolWorkerMessage) => void): void;
888
+ on(event: 'exit', listener: (code: number) => void): void;
889
+ on(event: 'error', listener: (error: Error) => void): void;
890
+
891
+ // NodeWorkerLike.terminate (method)
892
+ terminate(): Promise<number> | number;
893
+
894
+ // A module whose default export creates exporters for one worker
895
+ GeoSpecExporterModule: {
896
+ default: (context: {
897
+ readonly projectPath: string;
898
+ }) => Promise<readonly GeoSpecModelExporter[]>;
899
+ }
900
+
901
+ default: (context: {
902
+ readonly projectPath: string;
903
+ }) => Promise<readonly GeoSpecModelExporter[]>
904
+
807
905
  GeoSpecPoolHostMessage: {
808
906
  type: 'initialize';
809
907
  } | {
@@ -811,16 +909,12 @@ GeoSpecPoolHostMessage: {
811
909
  shard: GeoSpecPoolShard;
812
910
  testNamePattern?: string;
813
911
  testTimeout?: number;
814
- matcherWallBackstop?: number;
815
- forensic?: boolean;
816
912
  } | {
817
913
  /** List-only collection pass: register tests, run no bodies (R3 splitting). */
818
914
  type: 'list-tests';
819
915
  shardId: number;
820
916
  file: string;
821
917
  testTimeout?: number;
822
- matcherWallBackstop?: number;
823
- forensic?: boolean;
824
918
  } | {
825
919
  type: 'shutdown';
826
920
  }
@@ -880,16 +974,12 @@ GeoSpecPoolWorkerMessage: {
880
974
  } | {
881
975
  type: 'initialization-error';
882
976
  message: string;
977
+ /** The failure's error code, such as `ERR_MODULE_NOT_FOUND` for an absent engine. */
978
+ code?: string;
883
979
  } | {
884
980
  type: 'file-start';
885
981
  shardId: number;
886
982
  file: string;
887
- } | {
888
- type: 'forensic';
889
- shardId: number;
890
- name: string;
891
- value: number;
892
- unit: 'milliseconds' | 'count';
893
983
  } | {
894
984
  type: 'tests-listed';
895
985
  shardId: number;
@@ -918,25 +1008,6 @@ GeoSpecPoolWorkerMessage: {
918
1008
 
919
1009
  type: 'ready'
920
1010
 
921
- // One structured forensic measurement emitted by a runner
922
- GeoSpecForensicEvent: {
923
- type: 'forensic';
924
- name: string;
925
- value: number;
926
- unit: 'milliseconds' | 'count';
927
- shardId?: number;
928
- }
929
-
930
- type: 'forensic'
931
-
932
- name: string
933
-
934
- value: number
935
-
936
- unit: 'milliseconds' | 'count'
937
-
938
- shardId?: number
939
-
940
1011
  // Public GeoSpec runner lifecycle surface
941
1012
  GeoSpecRunner: {
942
1013
  /** Execute GeoSpec files and return a compact aggregate result. */
@@ -994,14 +1065,14 @@ GeoSpecRunnerEvent: {
994
1065
  } | {
995
1066
  type: 'run-complete';
996
1067
  result: GeoSpecRunnerResult;
997
- } | GeoSpecForensicEvent | {
1068
+ } | {
998
1069
  type: 'abort';
999
1070
  reason?: string;
1000
1071
  } | {
1001
1072
  type: 'close';
1002
1073
  }
1003
1074
 
1004
- type: 'forensic'
1075
+ type: 'run-start'
1005
1076
 
1006
1077
  // One GeoSpec test file executed by a worker-style runner
1007
1078
  GeoSpecRunnerFileResult: {
@@ -1113,16 +1184,12 @@ GeoSpecRunnerRunOptions: {
1113
1184
  testNamePattern?: string | RegExp;
1114
1185
  /** Timeout for each async test callback, in milliseconds. */
1115
1186
  testTimeout?: number;
1116
- /** Non-verdict matcher wall backstop. Milliseconds. */
1117
- matcherWallBackstop?: number;
1118
1187
  /**
1119
1188
  * Engine work-unit budget for this run's claims, replacing the runner's
1120
1189
  * `nativeAssertions.workUnitLimit`. A `loadModel` or `expectGeo` budget still
1121
1190
  * wins for its own claims.
1122
1191
  */
1123
1192
  workUnitLimit?: number;
1124
- /** Emit structured forensic measurements for this run. */
1125
- forensic?: boolean;
1126
1193
  /**
1127
1194
  * Stop after the first failing file (R1). Interactive fail-fast only —
1128
1195
  * never the default for reward runs, which want the complete red set.
@@ -1139,18 +1206,137 @@ GeoSpecRunnerRunOptions: {
1139
1206
  // Timeout for each async test callback, in milliseconds
1140
1207
  testTimeout?: number
1141
1208
 
1142
- // Non-verdict matcher wall backstop
1143
- matcherWallBackstop?: number
1144
-
1145
1209
  // Engine work-unit budget for this run's claims, replacing the runner's `nativeAssertions.workUnitLimit`
1146
1210
  workUnitLimit?: number
1147
1211
 
1148
- // Emit structured forensic measurements for this run
1149
- forensic?: boolean
1150
-
1151
1212
  // Stop after the first failing file (R1)
1152
1213
  bail?: boolean
1153
1214
 
1215
+ // Everything the pool needs that differs between Node and the browser
1216
+ GeoSpecPoolOptions: {
1217
+ /** Spawn one worker running `startGeoSpecPoolWorkerHost`. */
1218
+ createWorker: () => GeoSpecPoolWorkerHandle | Promise<GeoSpecPoolWorkerHandle>;
1219
+ /** Optional one-time worker initialization performed after its ready signal. */
1220
+ initializeWorker?: (worker: GeoSpecPoolWorkerHandle) => Promise<void> | void;
1221
+ /** Wait for each native worker's cleanup acknowledgement before terminating it. */
1222
+ gracefulShutdown?: boolean;
1223
+ /** Worker count. Omit to let the caller's host auto-size before calling. */
1224
+ workers: number;
1225
+ /** Optional scheduling telemetry. Absent = declared order, no memory class. */
1226
+ timings?: ShardTimings;
1227
+ /** Per-shard non-verdict watchdog, milliseconds (R11). */
1228
+ shardTimeout?: number;
1229
+ /** Split files whose recorded duration exceeds this. Milliseconds. */
1230
+ splitThreshold?: number;
1231
+ }
1232
+
1233
+ // Spawn one worker running `startGeoSpecPoolWorkerHost`
1234
+ createWorker: () => GeoSpecPoolWorkerHandle | Promise<GeoSpecPoolWorkerHandle>
1235
+
1236
+ // Optional one-time worker initialization performed after its ready signal
1237
+ initializeWorker?: (worker: GeoSpecPoolWorkerHandle) => Promise<void> | void
1238
+
1239
+ // Wait for each native worker's cleanup acknowledgement before terminating it
1240
+ gracefulShutdown?: boolean
1241
+
1242
+ // Worker count
1243
+ workers: number
1244
+
1245
+ // Optional scheduling telemetry
1246
+ timings?: ShardTimings
1247
+
1248
+ // Per-shard non-verdict watchdog, milliseconds (R11)
1249
+ shardTimeout?: number
1250
+
1251
+ // Split files whose recorded duration exceeds this
1252
+ splitThreshold?: number
1253
+
1254
+ // One shard's recorded cost
1255
+ ShardTiming: {
1256
+ /** Wall duration of the last recorded run, in milliseconds. */
1257
+ durationMs: number;
1258
+ /** Highest RSS observed for this shard, in bytes. Monotonic. */
1259
+ peakRssBytes: number;
1260
+ }
1261
+
1262
+ // Wall duration of the last recorded run, in milliseconds
1263
+ durationMs: number
1264
+
1265
+ // Highest RSS observed for this shard, in bytes
1266
+ peakRssBytes: number
1267
+
1268
+ // A mutable timings table
1269
+ ShardTimings: {
1270
+ /** Merge one observation. Peak RSS only ever grows. */
1271
+ record(shard: string, timing: ShardTiming): void;
1272
+ /** The hint for one shard, or `undefined` when unknown. */
1273
+ read(shard: string): ShardTiming | undefined;
1274
+ /** Every recorded shard, sorted by descending duration (longest-first). */
1275
+ longestFirst(): string[];
1276
+ /** Persist the table. Failure is silent: telemetry never fails a run. */
1277
+ save(): void;
1278
+ }
1279
+
1280
+ // Merge one observation
1281
+ // ShardTimings.record (method)
1282
+ record(shard: string, timing: ShardTiming): void;
1283
+
1284
+ // The hint for one shard, or `undefined` when unknown
1285
+ // ShardTimings.read (method)
1286
+ read(shard: string): ShardTiming | undefined;
1287
+
1288
+ // Every recorded shard, sorted by descending duration (longest-first)
1289
+ // ShardTimings.longestFirst (method)
1290
+ longestFirst(): string[];
1291
+
1292
+ // Persist the table
1293
+ // ShardTimings.save (method)
1294
+ save(): void;
1295
+
1296
+ // Options accepted by {@link startGeoSpecPoolWorkerHost}
1297
+ GeoSpecPoolWorkerHostOptions: {
1298
+ /** Filesystem containing the project and test modules. */
1299
+ filesystem: GeoSpecRunnerOptions['filesystem'];
1300
+ /** Native assertion client shared with this worker's model admissions. */
1301
+ nativeAssertions: GeoSpecRunnerOptions['nativeAssertions'];
1302
+ /** Managed native admissions, released after every shard and collection pass and before shutdown. */
1303
+ nativeModelLoader: ManagedGeoSpecNativeModelLoader;
1304
+ /** Additional in-memory modules made available to the VM. */
1305
+ builtinModules?: GeoSpecRunnerOptions['builtinModules'];
1306
+ /** Post a message to the pool host. */
1307
+ postMessage: (message: GeoSpecPoolWorkerMessage) => void;
1308
+ /** Subscribe to pool-host messages. */
1309
+ onHostMessage: (listener: (message: GeoSpecPoolHostMessage) => void) => void;
1310
+ /** Sample this worker's resident memory in bytes (R15 telemetry); optional. */
1311
+ measureMemoryBytes?: () => number | undefined;
1312
+ /** Release platform resources on shutdown, after the native subjects are released. */
1313
+ onShutdown?: () => Promise<void> | void;
1314
+ }
1315
+
1316
+ // Filesystem containing the project and test modules
1317
+ filesystem: GeoSpecRunnerOptions['filesystem']
1318
+
1319
+ // Native assertion client shared with this worker's model admissions
1320
+ nativeAssertions: GeoSpecRunnerOptions['nativeAssertions']
1321
+
1322
+ // Managed native admissions, released after every shard and collection pass and before shutdown
1323
+ nativeModelLoader: ManagedGeoSpecNativeModelLoader
1324
+
1325
+ // Additional in-memory modules made available to the VM
1326
+ builtinModules?: GeoSpecRunnerOptions['builtinModules']
1327
+
1328
+ // Post a message to the pool host
1329
+ postMessage: (message: GeoSpecPoolWorkerMessage) => void
1330
+
1331
+ // Subscribe to pool-host messages
1332
+ onHostMessage: (listener: (message: GeoSpecPoolHostMessage) => void) => void
1333
+
1334
+ // Sample this worker's resident memory in bytes (R15 telemetry)
1335
+ measureMemoryBytes?: () => number | undefined
1336
+
1337
+ // Release platform resources on shutdown, after the native subjects are released
1338
+ onShutdown?: () => Promise<void> | void
1339
+
1154
1340
  // Runner-independent native assertion client
1155
1341
  GeoSpecAssertionClient: {
1156
1342
  /**
@@ -1233,295 +1419,3 @@ GeoSpecAuthoringInvocation: {
1233
1419
  GeoSpecMatcherMethods: {
1234
1420
  [Name in GeoSpecMatcherName]: (...arguments_: Parameters<GeoSpecMatcher[Name]>) => Result;
1235
1421
  }
1236
-
1237
- // One positive-only ancillary query
1238
- // Remarks: An explicit claimId leaves the automatic sequence unchanged. Queries return full reports, including failed/refused reports, without assertion errors.
1239
- GeoSpecQueryOptions: {
1240
- readonly capability: GeoSpecQueryCapability;
1241
- readonly claimId?: string;
1242
- readonly payload?: unknown;
1243
- readonly subject: GeoSpecNativeSubject;
1244
- }
1245
-
1246
- readonly capability: GeoSpecQueryCapability
1247
-
1248
- readonly claimId?: string
1249
-
1250
- readonly payload?: unknown
1251
-
1252
- readonly subject: GeoSpecNativeSubject
1253
-
1254
- // Complete native minimum and ordered finite witnesses in canonical millimetres/Z-up
1255
- MinimumDistanceFact: {
1256
- readonly source: 'ap242';
1257
- readonly assurance: 'exact-brep';
1258
- readonly unit: 'mm';
1259
- readonly coordinateSystem: 'z-up';
1260
- readonly subjectHash: string;
1261
- readonly algorithmProfile: 'geospec-minimum-distance-v1';
1262
- readonly occurrences: readonly [string, string];
1263
- readonly distance: number;
1264
- readonly points: readonly [readonly [number, number, number], readonly [number, number, number]];
1265
- }
1266
-
1267
- readonly source: 'ap242'
1268
-
1269
- readonly assurance: 'exact-brep'
1270
-
1271
- readonly unit: 'mm'
1272
-
1273
- readonly coordinateSystem: 'z-up'
1274
-
1275
- readonly subjectHash: string
1276
-
1277
- readonly algorithmProfile: 'geospec-minimum-distance-v1'
1278
-
1279
- readonly occurrences: readonly [string, string]
1280
-
1281
- readonly distance: number
1282
-
1283
- readonly points: readonly [readonly [number, number, number], readonly [number, number, number]]
1284
-
1285
- // Complete AP242 minimum over two subject-bound occurrence paths
1286
- MinimumDistanceQuery: {
1287
- readonly capability: 'minimumDistance';
1288
- readonly subject: GeoSpecNativeSubject;
1289
- readonly payload: {
1290
- readonly pair: readonly [{
1291
- readonly occurrencePath: string;
1292
- }, {
1293
- readonly occurrencePath: string;
1294
- }];
1295
- };
1296
- }
1297
-
1298
- readonly capability: 'minimumDistance'
1299
-
1300
- readonly subject: GeoSpecNativeSubject
1301
-
1302
- readonly payload: {
1303
- readonly pair: readonly [{
1304
- readonly occurrencePath: string;
1305
- }, {
1306
- readonly occurrencePath: string;
1307
- }];
1308
- }
1309
-
1310
- // Geometry refusal and infrastructure interruption never masquerade as facts
1311
- MinimumDistanceResult: {
1312
- readonly status: 'complete';
1313
- readonly fact: MinimumDistanceFact;
1314
- } | {
1315
- readonly status: 'refused';
1316
- readonly code: 'unsupported-evidence' | 'invalid-selection' | 'work-limit' | 'analysis-limit' | 'resource-limit';
1317
- readonly message: string;
1318
- } | {
1319
- readonly status: 'interrupted';
1320
- readonly code: 'cancelled' | 'executor-exited' | 'deadline' | 'engine-error';
1321
- readonly message: string;
1322
- }
1323
-
1324
- readonly status: 'complete'
1325
-
1326
- // Flat native query transport options
1327
- GeoSpecNativeQueryOptions: Omit<GeoSpecNativeClaimOptions, 'arguments' | 'capability' | 'kind' | 'polarity'> & {
1328
- readonly capability: GeoSpecQueryCapability | 'minimumDistance';
1329
- readonly payload?: unknown;
1330
- }
1331
-
1332
- readonly engine: GeoSpecNativeEngine
1333
-
1334
- readonly claimId: string
1335
-
1336
- readonly evidenceProfile?: GeoSpecNativeEvidenceProfile
1337
-
1338
- readonly subjectSlot: string
1339
-
1340
- readonly workUnitLimit: number
1341
-
1342
- // The host's largest authored budget, reported as `details.maximumLimit` on `MATCHER_TIMEOUT`
1343
- readonly maximumWorkUnitLimit?: number
1344
-
1345
- readonly subject: GeoSpecNativeSubject
1346
-
1347
- readonly capability: GeoSpecQueryCapability | 'minimumDistance'
1348
-
1349
- readonly payload?: unknown
1350
-
1351
- // Existing positive-only ancillary operations owned by the native core
1352
- GeoSpecQueryCapability: Exclude<(typeof geoSpecQueryCapabilities)[number], 'minimumDistance'>
1353
-
1354
- // Explicit support state for one source-attributed inventory field
1355
- GeoSpecPmiField: {
1356
- readonly status: 'supported' | 'missing' | 'invalid' | 'ambiguous' | 'unsupported';
1357
- readonly value: Value | null;
1358
- readonly reason: string | null;
1359
- }
1360
-
1361
- readonly status: 'supported' | 'missing' | 'invalid' | 'ambiguous' | 'unsupported'
1362
-
1363
- readonly value: Value | null
1364
-
1365
- readonly reason: string | null
1366
-
1367
- // Original Part21 entity ID and exact source argument tokens
1368
- GeoSpecPmiRawEntity: {
1369
- readonly sourceId: number;
1370
- readonly kind: string;
1371
- readonly arguments: readonly string[];
1372
- }
1373
-
1374
- readonly sourceId: number
1375
-
1376
- readonly kind: string
1377
-
1378
- readonly arguments: readonly string[]
1379
-
1380
- // Source-authored scalar and Rust-normalized reduced rational millimetres
1381
- GeoSpecPmiNumber: {
1382
- readonly sourceId: number;
1383
- readonly authoredText: string;
1384
- readonly unitId: number;
1385
- readonly unitRecords: readonly GeoSpecPmiRawEntity[];
1386
- readonly millimetres: string;
1387
- readonly name: string;
1388
- }
1389
-
1390
- readonly sourceId: number
1391
-
1392
- readonly authoredText: string
1393
-
1394
- readonly unitId: number
1395
-
1396
- readonly unitRecords: readonly GeoSpecPmiRawEntity[]
1397
-
1398
- readonly millimetres: string
1399
-
1400
- readonly name: string
1401
-
1402
- // A uniquely forward-transferred face
1403
- GeoSpecPmiFaceAssociation: {
1404
- readonly sourceFaceId: number;
1405
- readonly occurrenceRoute: readonly number[];
1406
- readonly occurrence: number | null;
1407
- readonly publicFaceOrdinal: number;
1408
- }
1409
-
1410
- readonly sourceFaceId: number
1411
-
1412
- readonly occurrenceRoute: readonly number[]
1413
-
1414
- readonly occurrence: number | null
1415
-
1416
- readonly publicFaceOrdinal: number
1417
-
1418
- // One ordered role reference, including incomplete source/transfer evidence
1419
- GeoSpecPmiShapeReference: {
1420
- readonly sourceAspectId: number | null;
1421
- readonly sourceUsageIds: readonly number[];
1422
- readonly sourceItemIds: readonly number[];
1423
- readonly requestedRoute: GeoSpecPmiField<readonly number[]>;
1424
- readonly associations: GeoSpecPmiField<readonly GeoSpecPmiFaceAssociation[]>;
1425
- }
1426
-
1427
- readonly sourceAspectId: number | null
1428
-
1429
- readonly sourceUsageIds: readonly number[]
1430
-
1431
- readonly sourceItemIds: readonly number[]
1432
-
1433
- readonly requestedRoute: GeoSpecPmiField<readonly number[]>
1434
-
1435
- readonly associations: GeoSpecPmiField<readonly GeoSpecPmiFaceAssociation[]>
1436
-
1437
- // Normalized authored limits
1438
- GeoSpecPmiLimits: {
1439
- readonly lowerMillimetres: string;
1440
- readonly upperMillimetres: string;
1441
- readonly basis: 'authored-limits' | 'nominal-plus-minus';
1442
- }
1443
-
1444
- readonly lowerMillimetres: string
1445
-
1446
- readonly upperMillimetres: string
1447
-
1448
- readonly basis: 'authored-limits' | 'nominal-plus-minus'
1449
-
1450
- // Source record preserving semantic/presentation separation and ordered roles
1451
- GeoSpecPmiRecord: {
1452
- readonly sourceId: number;
1453
- readonly family: 'dimension' | 'datum' | 'tolerance' | 'presentation';
1454
- readonly channel: 'semantic' | 'presentation';
1455
- readonly kind: string;
1456
- readonly name: GeoSpecPmiField<string>;
1457
- readonly first: readonly GeoSpecPmiShapeReference[];
1458
- readonly second: readonly GeoSpecPmiShapeReference[];
1459
- readonly numbers: GeoSpecPmiField<readonly GeoSpecPmiNumber[]>;
1460
- readonly limits: GeoSpecPmiField<GeoSpecPmiLimits>;
1461
- readonly interpretation: GeoSpecPmiField<string>;
1462
- readonly raw: readonly GeoSpecPmiRawEntity[];
1463
- }
1464
-
1465
- readonly sourceId: number
1466
-
1467
- readonly family: 'dimension' | 'datum' | 'tolerance' | 'presentation'
1468
-
1469
- readonly channel: 'semantic' | 'presentation'
1470
-
1471
- readonly kind: string
1472
-
1473
- readonly name: GeoSpecPmiField<string>
1474
-
1475
- readonly first: readonly GeoSpecPmiShapeReference[]
1476
-
1477
- readonly second: readonly GeoSpecPmiShapeReference[]
1478
-
1479
- readonly numbers: GeoSpecPmiField<readonly GeoSpecPmiNumber[]>
1480
-
1481
- readonly limits: GeoSpecPmiField<GeoSpecPmiLimits>
1482
-
1483
- readonly interpretation: GeoSpecPmiField<string>
1484
-
1485
- readonly raw: readonly GeoSpecPmiRawEntity[]
1486
-
1487
- // Positive-only inventory value inside the ordinary canonical query report
1488
- GeoSpecPmiInventory: {
1489
- readonly contract: 'geospec.pmi.inventory/v1';
1490
- readonly status: 'semantic' | 'graphical-only' | 'empty';
1491
- readonly fileSchema: string;
1492
- readonly editionValidation: 'not-validated';
1493
- readonly records: readonly GeoSpecPmiRecord[];
1494
- }
1495
-
1496
- readonly contract: 'geospec.pmi.inventory/v1'
1497
-
1498
- readonly status: 'semantic' | 'graphical-only' | 'empty'
1499
-
1500
- readonly fileSchema: string
1501
-
1502
- readonly editionValidation: 'not-validated'
1503
-
1504
- readonly records: readonly GeoSpecPmiRecord[]
1505
-
1506
- // Strict inventory output limits
1507
- GeoSpecPmiQueryPayload: {
1508
- readonly maxRecords?: number;
1509
- readonly maxOutputBytes?: number;
1510
- }
1511
-
1512
- readonly maxRecords?: number
1513
-
1514
- readonly maxOutputBytes?: number
1515
-
1516
- // Complete inventory value
1517
- GeoSpecPmiQueryValue: {
1518
- readonly inventory: GeoSpecPmiInventory;
1519
- readonly subjectHash: string;
1520
- readonly provenance: Readonly<Record<string, unknown>>;
1521
- }
1522
-
1523
- readonly inventory: GeoSpecPmiInventory
1524
-
1525
- readonly subjectHash: string
1526
-
1527
- readonly provenance: Readonly<Record<string, unknown>>