geospec 0.1.0-beta.8 → 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 (56) hide show
  1. package/README.md +41 -8
  2. package/agent/geospec-authoring/SKILL.md +1 -0
  3. package/agent/geospec-authoring/api-index.md +5 -2
  4. package/agent/geospec-authoring/api-types-2.md +85 -0
  5. package/agent/geospec-authoring/api-types.md +2 -84
  6. package/agent/geospec-authoring/public-api-functions.md +44 -3
  7. package/agent/geospec-authoring/public-api-index.md +136 -97
  8. package/agent/geospec-authoring/public-api-types-2.md +108 -182
  9. package/agent/geospec-authoring/public-api-types-3.md +308 -28
  10. package/agent/geospec-authoring/public-api-types.md +1 -1
  11. package/agent/resources.js +12 -11
  12. package/agent/skills.json +3 -2
  13. package/dist/assertion-client/client.d.mts +3 -1
  14. package/dist/cli/cli.d.mts +48 -0
  15. package/dist/cli/cli.mjs +30 -0
  16. package/dist/cli/index.d.mts +3 -0
  17. package/dist/cli/index.mjs +1 -0
  18. package/dist/cli/main.d.mts +1 -0
  19. package/dist/cli/main.mjs +2 -0
  20. package/dist/cli/node-host.d.mts +26 -0
  21. package/dist/cli/node-host.mjs +1 -0
  22. package/dist/cli/wire-value.mjs +1 -0
  23. package/dist/config/define-config.d.mts +15 -0
  24. package/dist/config/define-config.mjs +2 -0
  25. package/dist/config/index.d.mts +4 -2
  26. package/dist/config/index.mjs +1 -1
  27. package/dist/config/node/load.d.mts +2 -1
  28. package/dist/config/node/load.mjs +1 -1
  29. package/dist/config/read-geospec-config.d.mts +47 -0
  30. package/dist/config/read-geospec-config.mjs +3 -0
  31. package/dist/config/types.d.mts +11 -22
  32. package/dist/config/validate.mjs +1 -1
  33. package/dist/engine/client.d.mts +3 -1
  34. package/dist/model/node/command-exporter.d.mts +2 -0
  35. package/dist/model/node/command-exporter.mjs +1 -1
  36. package/dist/runner/index.d.mts +1 -1
  37. package/dist/runner/native/index.mjs +1 -1
  38. package/dist/runner/native/native-serial-runner.mjs +1 -1
  39. package/dist/runner/node/engine.d.mts +40 -0
  40. package/dist/runner/node/engine.mjs +1 -0
  41. package/dist/runner/node/index.d.mts +4 -1
  42. package/dist/runner/node/index.mjs +1 -1
  43. package/dist/runner/node/node-vm-filesystem.mjs +1 -1
  44. package/dist/runner/node/pool-runner.d.mts +67 -0
  45. package/dist/runner/node/pool-runner.mjs +1 -0
  46. package/dist/runner/node/pool-worker-entry.d.mts +43 -0
  47. package/dist/runner/node/pool-worker-entry.mjs +1 -0
  48. package/dist/runner/pool/pool-messages.d.mts +2 -0
  49. package/dist/runner/pool/pool.d.mts +1 -1
  50. package/dist/runner/pool/pool.mjs +1 -1
  51. package/dist/runner/pool/worker-host.d.mts +1 -1
  52. package/dist/runner/run-geospec-module.mjs +7 -7
  53. package/dist/runner/types.d.mts +9 -6
  54. package/dist/runner/worker/index.d.mts +1 -1
  55. package/dist/runner/worker/serial-runner.mjs +1 -1
  56. package/package.json +18 -5
@@ -1,6 +1,6 @@
1
1
  # geospec — Types (2)
2
2
 
3
- 61 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: {
@@ -274,6 +274,8 @@ CommandExporterOptions: {
274
274
  readonly cwd?: string;
275
275
  /** Extra environment variables, merged over this process's. */
276
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;
277
279
  }
278
280
 
279
281
  readonly id: string
@@ -293,6 +295,9 @@ CommandExporterOptions: {
293
295
  // Extra environment variables, merged over this process's
294
296
  readonly env?: Readonly<Record<string, string>>
295
297
 
298
+ // Positive milliseconds one export may run before the command is killed and the export fails
299
+ readonly exportTimeout?: number
300
+
296
301
  // Collects suites, tests, assertions, and async completion state for one GeoSpec module execution
297
302
  GeoSpecCollector: {
298
303
  tests: GeoSpecTestCase[];
@@ -797,6 +802,106 @@ ManagedGeoSpecNativeModelLoader: GeoSpecNativeModelLoader & {
797
802
  // ManagedGeoSpecNativeModelLoader.releaseAll (method)
798
803
  releaseAll(): Promise<void>;
799
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
+
800
905
  GeoSpecPoolHostMessage: {
801
906
  type: 'initialize';
802
907
  } | {
@@ -869,6 +974,8 @@ GeoSpecPoolWorkerMessage: {
869
974
  } | {
870
975
  type: 'initialization-error';
871
976
  message: string;
977
+ /** The failure's error code, such as `ERR_MODULE_NOT_FOUND` for an absent engine. */
978
+ code?: string;
872
979
  } | {
873
980
  type: 'file-start';
874
981
  shardId: number;
@@ -1312,184 +1419,3 @@ GeoSpecAuthoringInvocation: {
1312
1419
  GeoSpecMatcherMethods: {
1313
1420
  [Name in GeoSpecMatcherName]: (...arguments_: Parameters<GeoSpecMatcher[Name]>) => Result;
1314
1421
  }
1315
-
1316
- // One positive-only ancillary query
1317
- // Remarks: An explicit claimId leaves the automatic sequence unchanged. Queries return full reports, including failed/refused reports, without assertion errors.
1318
- GeoSpecQueryOptions: {
1319
- readonly capability: GeoSpecQueryCapability;
1320
- readonly claimId?: string;
1321
- readonly payload?: unknown;
1322
- readonly subject: GeoSpecNativeSubject;
1323
- }
1324
-
1325
- readonly capability: GeoSpecQueryCapability
1326
-
1327
- readonly claimId?: string
1328
-
1329
- readonly payload?: unknown
1330
-
1331
- readonly subject: GeoSpecNativeSubject
1332
-
1333
- // Complete native minimum and ordered finite witnesses in canonical millimetres/Z-up
1334
- MinimumDistanceFact: {
1335
- readonly source: 'ap242';
1336
- readonly assurance: 'exact-brep';
1337
- readonly unit: 'mm';
1338
- readonly coordinateSystem: 'z-up';
1339
- readonly subjectHash: string;
1340
- readonly algorithmProfile: 'geospec-minimum-distance-v1';
1341
- readonly occurrences: readonly [string, string];
1342
- readonly distance: number;
1343
- readonly points: readonly [readonly [number, number, number], readonly [number, number, number]];
1344
- }
1345
-
1346
- readonly source: 'ap242'
1347
-
1348
- readonly assurance: 'exact-brep'
1349
-
1350
- readonly unit: 'mm'
1351
-
1352
- readonly coordinateSystem: 'z-up'
1353
-
1354
- readonly subjectHash: string
1355
-
1356
- readonly algorithmProfile: 'geospec-minimum-distance-v1'
1357
-
1358
- readonly occurrences: readonly [string, string]
1359
-
1360
- readonly distance: number
1361
-
1362
- readonly points: readonly [readonly [number, number, number], readonly [number, number, number]]
1363
-
1364
- // Complete AP242 minimum over two subject-bound occurrence paths
1365
- MinimumDistanceQuery: {
1366
- readonly capability: 'minimumDistance';
1367
- readonly subject: GeoSpecNativeSubject;
1368
- readonly payload: {
1369
- readonly pair: readonly [{
1370
- readonly occurrencePath: string;
1371
- }, {
1372
- readonly occurrencePath: string;
1373
- }];
1374
- };
1375
- }
1376
-
1377
- readonly capability: 'minimumDistance'
1378
-
1379
- readonly subject: GeoSpecNativeSubject
1380
-
1381
- readonly payload: {
1382
- readonly pair: readonly [{
1383
- readonly occurrencePath: string;
1384
- }, {
1385
- readonly occurrencePath: string;
1386
- }];
1387
- }
1388
-
1389
- // Geometry refusal and infrastructure interruption never masquerade as facts
1390
- MinimumDistanceResult: {
1391
- readonly status: 'complete';
1392
- readonly fact: MinimumDistanceFact;
1393
- } | {
1394
- readonly status: 'refused';
1395
- readonly code: 'unsupported-evidence' | 'invalid-selection' | 'work-limit' | 'analysis-limit' | 'resource-limit';
1396
- readonly message: string;
1397
- } | {
1398
- readonly status: 'interrupted';
1399
- readonly code: 'cancelled' | 'executor-exited' | 'deadline' | 'engine-error';
1400
- readonly message: string;
1401
- }
1402
-
1403
- readonly status: 'complete'
1404
-
1405
- // Flat native query transport options
1406
- GeoSpecNativeQueryOptions: Omit<GeoSpecNativeClaimOptions, 'arguments' | 'capability' | 'kind' | 'polarity'> & {
1407
- readonly capability: GeoSpecQueryCapability | 'minimumDistance';
1408
- readonly payload?: unknown;
1409
- }
1410
-
1411
- readonly engine: GeoSpecNativeEngine
1412
-
1413
- readonly claimId: string
1414
-
1415
- readonly evidenceProfile?: GeoSpecNativeEvidenceProfile
1416
-
1417
- readonly subjectSlot: string
1418
-
1419
- readonly workUnitLimit: number
1420
-
1421
- // The host's largest authored budget, reported as `details.maximumLimit` on `MATCHER_TIMEOUT`
1422
- readonly maximumWorkUnitLimit?: number
1423
-
1424
- readonly subject: GeoSpecNativeSubject
1425
-
1426
- readonly capability: GeoSpecQueryCapability | 'minimumDistance'
1427
-
1428
- readonly payload?: unknown
1429
-
1430
- // Existing positive-only ancillary operations owned by the native core
1431
- GeoSpecQueryCapability: Exclude<(typeof geoSpecQueryCapabilities)[number], 'minimumDistance'>
1432
-
1433
- // Explicit support state for one source-attributed inventory field
1434
- GeoSpecPmiField: {
1435
- readonly status: 'supported' | 'missing' | 'invalid' | 'ambiguous' | 'unsupported';
1436
- readonly value: Value | null;
1437
- readonly reason: string | null;
1438
- }
1439
-
1440
- readonly status: 'supported' | 'missing' | 'invalid' | 'ambiguous' | 'unsupported'
1441
-
1442
- readonly value: Value | null
1443
-
1444
- readonly reason: string | null
1445
-
1446
- // Original Part21 entity ID and exact source argument tokens
1447
- GeoSpecPmiRawEntity: {
1448
- readonly sourceId: number;
1449
- readonly kind: string;
1450
- readonly arguments: readonly string[];
1451
- }
1452
-
1453
- readonly sourceId: number
1454
-
1455
- readonly kind: string
1456
-
1457
- readonly arguments: readonly string[]
1458
-
1459
- // Source-authored scalar and Rust-normalized reduced rational millimetres
1460
- GeoSpecPmiNumber: {
1461
- readonly sourceId: number;
1462
- readonly authoredText: string;
1463
- readonly unitId: number;
1464
- readonly unitRecords: readonly GeoSpecPmiRawEntity[];
1465
- readonly millimetres: string;
1466
- readonly name: string;
1467
- }
1468
-
1469
- readonly sourceId: number
1470
-
1471
- readonly authoredText: string
1472
-
1473
- readonly unitId: number
1474
-
1475
- readonly unitRecords: readonly GeoSpecPmiRawEntity[]
1476
-
1477
- readonly millimetres: string
1478
-
1479
- readonly name: string
1480
-
1481
- // A uniquely forward-transferred face
1482
- GeoSpecPmiFaceAssociation: {
1483
- readonly sourceFaceId: number;
1484
- readonly occurrenceRoute: readonly number[];
1485
- readonly occurrence: number | null;
1486
- readonly publicFaceOrdinal: number;
1487
- }
1488
-
1489
- readonly sourceFaceId: number
1490
-
1491
- readonly occurrenceRoute: readonly number[]
1492
-
1493
- readonly occurrence: number | null
1494
-
1495
- readonly publicFaceOrdinal: number
@@ -1,6 +1,187 @@
1
1
  # geospec — Types (3)
2
2
 
3
- 17 top-level symbols. Signatures are verbatim typescript.
3
+ 31 top-level symbols. Signatures are verbatim typescript.
4
+
5
+ // One positive-only ancillary query
6
+ // Remarks: An explicit claimId leaves the automatic sequence unchanged. Queries return full reports without assertion errors. A query asserts nothing, so it never fails: one whose evidence is missing or cannot decide returns a refused report whose diagnostic names the reason, such as `GEOSPEC_UNSUPPORTED_EVIDENCE`.
7
+ GeoSpecQueryOptions: {
8
+ readonly capability: GeoSpecQueryCapability;
9
+ readonly claimId?: string;
10
+ readonly payload?: unknown;
11
+ readonly subject: GeoSpecNativeSubject;
12
+ }
13
+
14
+ readonly capability: GeoSpecQueryCapability
15
+
16
+ readonly claimId?: string
17
+
18
+ readonly payload?: unknown
19
+
20
+ readonly subject: GeoSpecNativeSubject
21
+
22
+ // Complete native minimum and ordered finite witnesses in canonical millimetres/Z-up
23
+ MinimumDistanceFact: {
24
+ readonly source: 'ap242';
25
+ readonly assurance: 'exact-brep';
26
+ readonly unit: 'mm';
27
+ readonly coordinateSystem: 'z-up';
28
+ readonly subjectHash: string;
29
+ readonly algorithmProfile: 'geospec-minimum-distance-v1';
30
+ readonly occurrences: readonly [string, string];
31
+ readonly distance: number;
32
+ readonly points: readonly [readonly [number, number, number], readonly [number, number, number]];
33
+ }
34
+
35
+ readonly source: 'ap242'
36
+
37
+ readonly assurance: 'exact-brep'
38
+
39
+ readonly unit: 'mm'
40
+
41
+ readonly coordinateSystem: 'z-up'
42
+
43
+ readonly subjectHash: string
44
+
45
+ readonly algorithmProfile: 'geospec-minimum-distance-v1'
46
+
47
+ readonly occurrences: readonly [string, string]
48
+
49
+ readonly distance: number
50
+
51
+ readonly points: readonly [readonly [number, number, number], readonly [number, number, number]]
52
+
53
+ // Complete AP242 minimum over two subject-bound occurrence paths
54
+ MinimumDistanceQuery: {
55
+ readonly capability: 'minimumDistance';
56
+ readonly subject: GeoSpecNativeSubject;
57
+ readonly payload: {
58
+ readonly pair: readonly [{
59
+ readonly occurrencePath: string;
60
+ }, {
61
+ readonly occurrencePath: string;
62
+ }];
63
+ };
64
+ }
65
+
66
+ readonly capability: 'minimumDistance'
67
+
68
+ readonly subject: GeoSpecNativeSubject
69
+
70
+ readonly payload: {
71
+ readonly pair: readonly [{
72
+ readonly occurrencePath: string;
73
+ }, {
74
+ readonly occurrencePath: string;
75
+ }];
76
+ }
77
+
78
+ // Geometry refusal and infrastructure interruption never masquerade as facts
79
+ MinimumDistanceResult: {
80
+ readonly status: 'complete';
81
+ readonly fact: MinimumDistanceFact;
82
+ } | {
83
+ readonly status: 'refused';
84
+ readonly code: 'unsupported-evidence' | 'invalid-selection' | 'work-limit' | 'analysis-limit' | 'resource-limit';
85
+ readonly message: string;
86
+ } | {
87
+ readonly status: 'interrupted';
88
+ readonly code: 'cancelled' | 'executor-exited' | 'deadline' | 'engine-error';
89
+ readonly message: string;
90
+ }
91
+
92
+ readonly status: 'complete'
93
+
94
+ // Flat native query transport options
95
+ GeoSpecNativeQueryOptions: Omit<GeoSpecNativeClaimOptions, 'arguments' | 'capability' | 'kind' | 'polarity'> & {
96
+ readonly capability: GeoSpecQueryCapability | 'minimumDistance';
97
+ readonly payload?: unknown;
98
+ }
99
+
100
+ readonly engine: GeoSpecNativeEngine
101
+
102
+ readonly claimId: string
103
+
104
+ readonly evidenceProfile?: GeoSpecNativeEvidenceProfile
105
+
106
+ readonly subjectSlot: string
107
+
108
+ readonly workUnitLimit: number
109
+
110
+ // The host's largest authored budget, reported as `details.maximumLimit` on `MATCHER_TIMEOUT`
111
+ readonly maximumWorkUnitLimit?: number
112
+
113
+ readonly subject: GeoSpecNativeSubject
114
+
115
+ readonly capability: GeoSpecQueryCapability | 'minimumDistance'
116
+
117
+ readonly payload?: unknown
118
+
119
+ // Existing positive-only ancillary operations owned by the native core
120
+ GeoSpecQueryCapability: Exclude<(typeof geoSpecQueryCapabilities)[number], 'minimumDistance'>
121
+
122
+ // Explicit support state for one source-attributed inventory field
123
+ GeoSpecPmiField: {
124
+ readonly status: 'supported' | 'missing' | 'invalid' | 'ambiguous' | 'unsupported';
125
+ readonly value: Value | null;
126
+ readonly reason: string | null;
127
+ }
128
+
129
+ readonly status: 'supported' | 'missing' | 'invalid' | 'ambiguous' | 'unsupported'
130
+
131
+ readonly value: Value | null
132
+
133
+ readonly reason: string | null
134
+
135
+ // Original Part21 entity ID and exact source argument tokens
136
+ GeoSpecPmiRawEntity: {
137
+ readonly sourceId: number;
138
+ readonly kind: string;
139
+ readonly arguments: readonly string[];
140
+ }
141
+
142
+ readonly sourceId: number
143
+
144
+ readonly kind: string
145
+
146
+ readonly arguments: readonly string[]
147
+
148
+ // Source-authored scalar and Rust-normalized reduced rational millimetres
149
+ GeoSpecPmiNumber: {
150
+ readonly sourceId: number;
151
+ readonly authoredText: string;
152
+ readonly unitId: number;
153
+ readonly unitRecords: readonly GeoSpecPmiRawEntity[];
154
+ readonly millimetres: string;
155
+ readonly name: string;
156
+ }
157
+
158
+ readonly sourceId: number
159
+
160
+ readonly authoredText: string
161
+
162
+ readonly unitId: number
163
+
164
+ readonly unitRecords: readonly GeoSpecPmiRawEntity[]
165
+
166
+ readonly millimetres: string
167
+
168
+ readonly name: string
169
+
170
+ // A uniquely forward-transferred face
171
+ GeoSpecPmiFaceAssociation: {
172
+ readonly sourceFaceId: number;
173
+ readonly occurrenceRoute: readonly number[];
174
+ readonly occurrence: number | null;
175
+ readonly publicFaceOrdinal: number;
176
+ }
177
+
178
+ readonly sourceFaceId: number
179
+
180
+ readonly occurrenceRoute: readonly number[]
181
+
182
+ readonly occurrence: number | null
183
+
184
+ readonly publicFaceOrdinal: number
4
185
 
5
186
  // One ordered role reference, including incomplete source/transfer evidence
6
187
  GeoSpecPmiShapeReference: {
@@ -200,6 +381,81 @@ GeoSpecFixedMatcherDescriptor: {
200
381
 
201
382
  readonly mode: 'sync'
202
383
 
384
+ // The platform the CLI runs against
385
+ GeoSpecCliHost: {
386
+ /** Absolute project root for a relative `projectPath`. */
387
+ cwd(): string;
388
+ write(line: string): void;
389
+ /** Recursive discovery filesystem. */
390
+ discoveryFileSystem(projectPath: string): Parameters<typeof discoverGeoSpecFiles>[0]['filesystem'];
391
+ /**
392
+ * Import the project's `geospec.config.*`, or the explicit one, for its data fields.
393
+ * @throws Error when the config is ambiguous, invalid or fails to import.
394
+ */
395
+ loadConfig(options: {
396
+ projectPath: string;
397
+ configPath: string | undefined;
398
+ }): Promise<{
399
+ readonly configPath?: string;
400
+ readonly options: GeoSpecConfigData;
401
+ }>;
402
+ /** Build the runner the selected files execute on; its workers import the same config for its exporters. */
403
+ createRunner(options: {
404
+ projectPath: string;
405
+ configPath: string | undefined;
406
+ workers: number | undefined;
407
+ shardTimeout: number | undefined;
408
+ }): GeoSpecRunner;
409
+ }
410
+
411
+ // Absolute project root for a relative `projectPath`
412
+ // GeoSpecCliHost.cwd (method)
413
+ cwd(): string;
414
+
415
+ // GeoSpecCliHost.write (method)
416
+ write(line: string): void;
417
+
418
+ // Recursive discovery filesystem
419
+ // GeoSpecCliHost.discoveryFileSystem (method)
420
+ discoveryFileSystem(projectPath: string): Parameters<typeof discoverGeoSpecFiles>[0]['filesystem'];
421
+
422
+ // Import the project's `geospec.config.*`, or the explicit one, for its data fields
423
+ // Throws: Error when the config is ambiguous, invalid or fails to import.
424
+ // GeoSpecCliHost.loadConfig (method)
425
+ loadConfig(options: {
426
+ projectPath: string;
427
+ configPath: string | undefined;
428
+ }): Promise<{
429
+ readonly configPath?: string;
430
+ readonly options: GeoSpecConfigData;
431
+ }>;
432
+
433
+ // Build the runner the selected files execute on
434
+ // GeoSpecCliHost.createRunner (method)
435
+ createRunner(options: {
436
+ projectPath: string;
437
+ configPath: string | undefined;
438
+ workers: number | undefined;
439
+ shardTimeout: number | undefined;
440
+ }): GeoSpecRunner;
441
+
442
+ // Options for {@link createNodeGeoSpecCliHost}
443
+ NodeGeoSpecCliHostOptions: {
444
+ /** Report sink used by embedding hosts and tests; defaults to stdout. */
445
+ readonly reportStream?: (text: string) => void;
446
+ /**
447
+ * URLs of modules each pool worker imports for exporters that precede the config's, so a host such as `tau test`
448
+ * can run a project with no `geospec.config.*` (see `GeoSpecExporterModule` in `geospec/runner/node`).
449
+ */
450
+ readonly exporterModules?: readonly string[];
451
+ }
452
+
453
+ // Report sink used by embedding hosts and tests
454
+ readonly reportStream?: (text: string) => void
455
+
456
+ // URLs of modules each pool worker imports for exporters that precede the config's, so a host such as `tau test` can run a project with no `geospec.config.*` (see `GeoSpecExporterModule` in `geospec/runner/node`)
457
+ readonly exporterModules?: readonly string[]
458
+
203
459
  // Installed Vitest matcher map and lifecycle settlement hook
204
460
  GeoSpecVitestAdapter: {
205
461
  readonly matchers: GeoSpecVitestMatcherMap;
@@ -211,8 +467,42 @@ GeoSpecVitestAdapter: {
211
467
  // GeoSpecVitestAdapter.flush (method)
212
468
  flush(): Promise<void>;
213
469
 
470
+ // Options for {@link readGeoSpecConfig}
471
+ ReadGeoSpecConfigOptions: {
472
+ /** The project filesystem; paths are rooted, as the spec VM reads them. */
473
+ readonly filesystem: VmFileSystem;
474
+ /** Rooted directory holding the config, in the filesystem's spelling: `''` for its root, else `'sub/dir'`. */
475
+ readonly projectPath: string;
476
+ }
477
+
478
+ // The project filesystem
479
+ readonly filesystem: VmFileSystem
480
+
481
+ // Rooted directory holding the config, in the filesystem's spelling
482
+ readonly projectPath: string
483
+
484
+ // Outcome of {@link readGeoSpecConfig}
485
+ ReadGeoSpecConfigResult: {
486
+ readonly status: 'absent';
487
+ } | {
488
+ readonly status: 'applied';
489
+ readonly configPath: string;
490
+ readonly options: GeoSpecConfigData;
491
+ } | {
492
+ readonly status: 'not-applied';
493
+ readonly configPath: string;
494
+ /**
495
+ * `unresolved-import`: the config imports a package other than `geospec/config`, which only a
496
+ * native run can provide. `invalid`: it does not bundle, throws, or is not a valid config.
497
+ */
498
+ readonly reason: 'unresolved-import' | 'invalid';
499
+ readonly message: string;
500
+ }
501
+
502
+ readonly status: 'absent'
503
+
214
504
  // Trusted project configuration using existing discovery and runner options
215
- // Remarks: Omitted values keep their existing owner's defaults. Defined overrides replace whole fields, including empty arrays, false and the subjects map. Existing discovery currently treats an absent or empty include array as its default pattern. Preserving [] here does not change that consumer behavior. This is configuration data, not a canonical engine plan or a geometry result.
505
+ // Remarks: Omitted values keep their existing owner's defaults. Defined overrides replace whole fields, including empty arrays and false. Existing discovery currently treats an absent or empty include array as its default pattern. Preserving [] here does not change that consumer behavior. This is configuration data, not a canonical engine plan or a geometry result.
216
506
  GeoSpecConfig: {
217
507
  include?: readonly string[];
218
508
  exclude?: readonly string[];
@@ -220,10 +510,12 @@ GeoSpecConfig: {
220
510
  /** Positive finite milliseconds; the runner owns its default. */
221
511
  testTimeout?: number;
222
512
  bail?: boolean;
223
- cache?: boolean;
224
- /** Requested cache location only; loading configuration creates no store. */
225
- cacheDirectory?: string;
226
- subjects?: Readonly<Record<string, GeoSpecTauProjectDescriptor>>;
513
+ /**
514
+ * Model exporters for `loadModel({ file })`: the first whose `extensions` claims the file exports
515
+ * it, so order is the override. STEP and GLB sources need none. Only a runner that executes the
516
+ * config natively reads them; a host that holds its own exporters reads the data fields only.
517
+ */
518
+ exporters?: readonly GeoSpecModelExporter[];
227
519
  }
228
520
 
229
521
  include?: readonly string[]
@@ -237,34 +529,22 @@ GeoSpecConfig: {
237
529
 
238
530
  bail?: boolean
239
531
 
240
- cache?: boolean
241
-
242
- // Requested cache location only
243
- cacheDirectory?: string
532
+ // Model exporters for `loadModel({ file })`
533
+ exporters?: readonly GeoSpecModelExporter[]
244
534
 
245
- subjects?: Readonly<Record<string, GeoSpecTauProjectDescriptor>>
535
+ // The config's data fields
536
+ GeoSpecConfigData: Omit<GeoSpecConfig, 'exporters'>
246
537
 
247
- // Imported Tau project data for later host resolution
248
- // Remarks: This descriptor does not validate the original manifest bytes or its schema, admit an asset, export geometry, or establish finalized-artifact provenance.
249
- GeoSpecTauProjectDescriptor: {
250
- readonly kind: 'tau-project';
251
- /** Normalized project-relative POSIX path identifying the imported manifest. */
252
- readonly manifestPath: string;
253
- readonly manifest: Readonly<Record<string, JSONValue>>;
254
- readonly format: 'step' | 'glb';
255
- readonly parameters?: Readonly<Record<string, JSONValue>>;
256
- }
257
-
258
- readonly kind: 'tau-project'
538
+ include?: readonly string[]
259
539
 
260
- // Normalized project-relative POSIX path identifying the imported manifest
261
- readonly manifestPath: string
540
+ exclude?: readonly string[]
262
541
 
263
- readonly manifest: Readonly<Record<string, JSONValue>>
542
+ testNamePattern?: string
264
543
 
265
- readonly format: 'step' | 'glb'
544
+ // Positive finite milliseconds
545
+ testTimeout?: number
266
546
 
267
- readonly parameters?: Readonly<Record<string, JSONValue>>
547
+ bail?: boolean
268
548
 
269
549
  // Resolved file identity and validated configuration data
270
550
  LoadedGeoSpecConfig: {