geospec 0.1.0-beta.6 → 0.1.0-beta.8

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 (58) hide show
  1. package/agent/doctrine.md +17 -2
  2. package/agent/geospec-authoring/SKILL.md +47 -47
  3. package/agent/geospec-authoring/api-functions.md +1 -16
  4. package/agent/geospec-authoring/api-index.md +119 -111
  5. package/agent/geospec-authoring/api-types.md +218 -170
  6. package/agent/geospec-authoring/public-api-functions.md +29 -22
  7. package/agent/geospec-authoring/public-api-index.md +294 -276
  8. package/agent/geospec-authoring/public-api-types-2.md +222 -287
  9. package/agent/geospec-authoring/public-api-types-3.md +176 -99
  10. package/agent/geospec-authoring/public-api-types.md +236 -125
  11. package/agent/resources.js +12 -12
  12. package/agent/skills.json +2 -2
  13. package/dist/assertion-client/client.d.mts +1 -1
  14. package/dist/assertion-client/client.mjs +1 -1
  15. package/dist/config/index.d.mts +1 -2
  16. package/dist/config/index.mjs +1 -1
  17. package/dist/config/types.d.mts +0 -3
  18. package/dist/config/validate.mjs +1 -1
  19. package/dist/engine/client.mjs +1 -1
  20. package/dist/mesh/index.d.mts +2 -2
  21. package/dist/model/index.d.mts +3 -3
  22. package/dist/model/index.mjs +1 -1
  23. package/dist/model/mesh-evidence-matchers.d.mts +12 -0
  24. package/dist/model/mesh-evidence-matchers.mjs +1 -0
  25. package/dist/model/native-model-loader.d.mts +10 -8
  26. package/dist/model/native-model-loader.mjs +1 -1
  27. package/dist/model/node/command-exporter.d.mts +31 -0
  28. package/dist/model/node/command-exporter.mjs +1 -0
  29. package/dist/model/node/index.d.mts +2 -0
  30. package/dist/model/node/index.mjs +1 -0
  31. package/dist/model/region-scope.mjs +1 -1
  32. package/dist/model/types.d.mts +132 -68
  33. package/dist/runner/collector.d.mts +0 -2
  34. package/dist/runner/collector.mjs +1 -1
  35. package/dist/runner/node/index.d.mts +2 -0
  36. package/dist/runner/node/index.mjs +1 -0
  37. package/dist/runner/node/node-vm-filesystem.d.mts +22 -0
  38. package/dist/runner/node/node-vm-filesystem.mjs +1 -0
  39. package/dist/runner/pool/events.mjs +1 -0
  40. package/dist/runner/pool/pool-messages.d.mts +0 -10
  41. package/dist/runner/pool/pool.d.mts +36 -0
  42. package/dist/runner/pool/pool.mjs +1 -0
  43. package/dist/runner/pool/shard-planner.mjs +1 -0
  44. package/dist/runner/pool/shard-timings.d.mts +36 -0
  45. package/dist/runner/pool/transport.mjs +1 -0
  46. package/dist/runner/pool/worker-host.d.mts +36 -0
  47. package/dist/runner/pool/worker-host.mjs +1 -0
  48. package/dist/runner/run-geospec-module.mjs +1 -1
  49. package/dist/runner/types.d.mts +0 -4
  50. package/dist/runner/worker/index.d.mts +7 -2
  51. package/dist/runner/worker/index.mjs +1 -1
  52. package/dist/runner/worker/runner-types.d.mts +2 -14
  53. package/dist/runner/worker/serial-runner.mjs +1 -1
  54. package/package.json +14 -4
  55. package/dist/config/tau-project-artifact.d.mts +0 -54
  56. package/dist/config/tau-project-artifact.mjs +0 -3
  57. package/dist/model/export-intent.d.mts +0 -79
  58. package/dist/model/export-intent.mjs +0 -1
@@ -1,6 +1,6 @@
1
1
  # geospec — Types
2
2
 
3
- 69 top-level symbols. Signatures are verbatim typescript.
3
+ 67 top-level symbols. Signatures are verbatim typescript.
4
4
 
5
5
  // A model admitted by one live GeoSpec host scope
6
6
  GeoSpecSubject: {
@@ -1343,70 +1343,6 @@ Vec3: readonly [number, number, number]
1343
1343
  // Numeric 3D vector
1344
1344
  GeoSpecVec3: readonly [number, number, number]
1345
1345
 
1346
- // Runtime route metadata used to decide whether a runtime export can honor GeoSpec evidence requirements
1347
- GeoSpecExportRoute: Partial<ExportRoute> & {
1348
- kernelId?: string;
1349
- sourceFormat?: string;
1350
- targetFormat?: string;
1351
- transcoderId?: string;
1352
- fidelity?: string;
1353
- exportOptions?: {
1354
- schema?: {
1355
- properties?: Record<string, unknown>;
1356
- };
1357
- defaults?: Record<string, unknown>;
1358
- };
1359
- }
1360
-
1361
- RuntimeBackedModelFormat: Exclude<GeoSpecModelFormat, 'mesh-buffer'>
1362
-
1363
- // Runtime client shape for route-aware Tau runtimes
1364
- RuntimeClientWithRoutes: GeoSpecRuntimeClient & {
1365
- bestRouteFor(format: string, options?: {
1366
- readonly kernelId?: string;
1367
- }): GeoSpecExportRoute | undefined;
1368
- }
1369
-
1370
- open: (input: Pick<Parameters<RuntimeClient['open']>[0], 'source' | 'parameters' | 'stage' | 'watch' | 'signal'>) => Pick<ReturnType<RuntimeClient['open']>, 'export' | 'close'>
1371
-
1372
- // RuntimeClientWithRoutes.on (method)
1373
- on?(event: 'telemetry', handler: (batch: {
1374
- readonly entries: ReadonlyArray<{
1375
- name: string;
1376
- duration: number;
1377
- startTime: number;
1378
- workerTimeOrigin: number;
1379
- }>;
1380
- }) => void): () => void;
1381
-
1382
- // RuntimeClientWithRoutes.bestRouteFor (method)
1383
- bestRouteFor(format: string, options?: {
1384
- readonly kernelId?: string;
1385
- }): GeoSpecExportRoute | undefined;
1386
-
1387
- // Resolved runtime export request and provenance for a GeoSpec model load
1388
- RuntimeExportIntent: {
1389
- options: Record<string, unknown>;
1390
- provenance: GeometryExportIntent;
1391
- sourceUnit: GeoSpecUnit;
1392
- }
1393
-
1394
- options: Record<string, unknown>
1395
-
1396
- provenance: GeometryExportIntent
1397
-
1398
- sourceUnit: GeoSpecUnit
1399
-
1400
- // Structured failure returned when a runtime cannot provide the requested GeoSpec evidence
1401
- RuntimeExportIntentFailure: {
1402
- success: false;
1403
- diagnostics: GeometryDiagnostic[];
1404
- }
1405
-
1406
- success: false
1407
-
1408
- diagnostics: GeometryDiagnostic[]
1409
-
1410
1346
  // Defaults accepted by {@link import ('./load-model.js').createModelLoader}
1411
1347
  CreateModelLoaderOptions: {
1412
1348
  /** Initialized compiled engine supplied by the host, never selected by an authored spec. */
@@ -1415,11 +1351,9 @@ CreateModelLoaderOptions: {
1415
1351
  readSource?: GeoSpecNativeSourceReader;
1416
1352
  /** Geometry format to export when an individual call does not specify one. */
1417
1353
  format?: GeoSpecModelFormat;
1418
- /** Runtime client or lazy runtime factory. */
1419
- runtime?: GeoSpecRuntimeClient | GeoSpecRuntimeClientFactory;
1420
- /** Source-specific runtime adapters, e.g. host-provided GPL-isolated kernels. */
1421
- sourceAdapters?: readonly GeoSpecRuntimeSourceAdapter[];
1422
- /** Project root used by runtime integrations. */
1354
+ /** Model exporters for source-kind files; the first whose `extensions` claim the file exports it. */
1355
+ exporters?: readonly GeoSpecModelExporter[];
1356
+ /** Absolute project root passed to the exporter. */
1423
1357
  projectPath?: string;
1424
1358
  /** STEP reader strategy used for STEP sources or exports. */
1425
1359
  stepStreaming?: StepStreamingMode;
@@ -1440,13 +1374,10 @@ CreateModelLoaderOptions: {
1440
1374
  // Geometry format to export when an individual call does not specify one
1441
1375
  format?: GeoSpecModelFormat
1442
1376
 
1443
- // Runtime client or lazy runtime factory
1444
- runtime?: GeoSpecRuntimeClient | GeoSpecRuntimeClientFactory
1377
+ // Model exporters for source-kind files
1378
+ exporters?: readonly GeoSpecModelExporter[]
1445
1379
 
1446
- // Source-specific runtime adapters, e.g
1447
- sourceAdapters?: readonly GeoSpecRuntimeSourceAdapter[]
1448
-
1449
- // Project root used by runtime integrations
1380
+ // Absolute project root passed to the exporter
1450
1381
  projectPath?: string
1451
1382
 
1452
1383
  // STEP reader strategy used for STEP sources or exports
@@ -1461,6 +1392,33 @@ CreateModelLoaderOptions: {
1461
1392
  // Angular tolerance in degrees used while meshing exact BRep evidence
1462
1393
  meshAngularToleranceDegrees?: number
1463
1394
 
1395
+ // What a {@link GeoSpecModelExporter} declares it can do
1396
+ GeoSpecExporterCapabilities: {
1397
+ /** The formats `export` produces; at least one. A GLB-only exporter refuses STEP loads up front. */
1398
+ readonly formats: readonly GeoSpecExportFormat[];
1399
+ /** Accepts `parameters`. Without it, a load that passes parameters refuses. */
1400
+ readonly parameters?: boolean;
1401
+ /** Crops to `region` (an axis-aligned millimetre box) before export. Without it, a region load refuses. */
1402
+ readonly region?: boolean;
1403
+ /** Accepts `inline` sources, which back `loadModel({ code })`. Without it, an inline load refuses. */
1404
+ readonly inlineSources?: boolean;
1405
+ }
1406
+
1407
+ // The formats `export` produces
1408
+ readonly formats: readonly GeoSpecExportFormat[]
1409
+
1410
+ // Accepts `parameters`
1411
+ readonly parameters?: boolean
1412
+
1413
+ // Crops to `region` (an axis-aligned millimetre box) before export
1414
+ readonly region?: boolean
1415
+
1416
+ // Accepts `inline` sources, which back `loadModel({ code })`
1417
+ readonly inlineSources?: boolean
1418
+
1419
+ // Formats a {@link GeoSpecModelExporter} may produce from a source-kind file
1420
+ GeoSpecExportFormat: Extract<GeoSpecModelFormat, 'glb' | 'step'>
1421
+
1464
1422
  // Axis-aligned crop box in canonical Z-up millimetres
1465
1423
  GeoSpecLoadRegion: {
1466
1424
  readonly min: readonly [number, number, number];
@@ -1471,13 +1429,140 @@ GeoSpecLoadRegion: {
1471
1429
 
1472
1430
  readonly max: readonly [number, number, number]
1473
1431
 
1432
+ // The bytes an exporter returns, in the canonical Z-up millimetre frame
1433
+ GeoSpecModelArtifact: {
1434
+ readonly bytes: Uint8Array<ArrayBuffer>;
1435
+ readonly format: GeoSpecExportFormat;
1436
+ /** Unit of raw GLB coordinates; defaults to `'mm'`. STEP carries its own unit. */
1437
+ readonly sourceUnit?: GeoSpecUnit;
1438
+ /** External resources the primary bytes reference, by name. */
1439
+ readonly resources?: ReadonlyArray<{
1440
+ readonly name: string;
1441
+ readonly bytes: Uint8Array<ArrayBuffer>;
1442
+ }>;
1443
+ /**
1444
+ * Every source file the export read, as a path from the project root with its SHA-256 (64 hex digits,
1445
+ * optionally prefixed `sha256:`), or `'missing'` for a file the export looked for and did not find. The
1446
+ * load records it as the subject's source revision.
1447
+ */
1448
+ readonly consumedSources?: GeoSpecConsumedSources;
1449
+ /** Notices from a successful export, admitted with the subject so its evidence keeps them. */
1450
+ readonly diagnostics?: readonly GeometryDiagnostic[];
1451
+ /** The export options the exporter applied, recorded in the load evidence beside the exporter id. */
1452
+ readonly exportOptions?: Readonly<Record<string, unknown>>;
1453
+ }
1454
+
1455
+ readonly bytes: Uint8Array<ArrayBuffer>
1456
+
1457
+ readonly format: GeoSpecExportFormat
1458
+
1459
+ // Unit of raw GLB coordinates
1460
+ readonly sourceUnit?: GeoSpecUnit
1461
+
1462
+ // External resources the primary bytes reference, by name
1463
+ readonly resources?: ReadonlyArray<{
1464
+ readonly name: string;
1465
+ readonly bytes: Uint8Array<ArrayBuffer>;
1466
+ }>
1467
+
1468
+ // Every source file the export read, as a path from the project root with its SHA-256 (64 hex digits, optionally prefixed `sha256:`), or `'missing'` for a file the export looked for and did not find
1469
+ readonly consumedSources?: GeoSpecConsumedSources
1470
+
1471
+ // Notices from a successful export, admitted with the subject so its evidence keeps them
1472
+ readonly diagnostics?: readonly GeometryDiagnostic[]
1473
+
1474
+ // The export options the exporter applied, recorded in the load evidence beside the exporter id
1475
+ readonly exportOptions?: Readonly<Record<string, unknown>>
1476
+
1477
+ // Turns a source-kind model file into GLB or STEP bytes for GeoSpec
1478
+ GeoSpecModelExporter: {
1479
+ readonly id: string;
1480
+ readonly extensions: readonly string[];
1481
+ readonly capabilities: GeoSpecExporterCapabilities;
1482
+ export(request: GeoSpecModelExportRequest): Promise<GeoSpecModelArtifact>;
1483
+ /**
1484
+ * The sources an export of `file` would read now, without exporting. With it, the loader reuses an
1485
+ * earlier identical load in the same scope when every digest still matches; without it, every file
1486
+ * load exports afresh.
1487
+ */
1488
+ revision?(request: Pick<GeoSpecModelExportRequest, 'file' | 'projectPath'>): Promise<GeoSpecConsumedSources | undefined>;
1489
+ /**
1490
+ * Releases what the exporter created for one scope. The loader calls it from `releaseAll` for every
1491
+ * exporter it exported through in that scope; the exporter stays usable for the next one.
1492
+ */
1493
+ close?(): Promise<void>;
1494
+ }
1495
+
1496
+ readonly id: string
1497
+
1498
+ readonly extensions: readonly string[]
1499
+
1500
+ readonly capabilities: GeoSpecExporterCapabilities
1501
+
1502
+ // GeoSpecModelExporter.export (method)
1503
+ export(request: GeoSpecModelExportRequest): Promise<GeoSpecModelArtifact>;
1504
+
1505
+ // The sources an export of `file` would read now, without exporting
1506
+ // GeoSpecModelExporter.revision (method)
1507
+ revision?(request: Pick<GeoSpecModelExportRequest, 'file' | 'projectPath'>): Promise<GeoSpecConsumedSources | undefined>;
1508
+
1509
+ // Releases what the exporter created for one scope
1510
+ // GeoSpecModelExporter.close (method)
1511
+ close?(): Promise<void>;
1512
+
1513
+ // One export request
1514
+ GeoSpecModelExportRequest: {
1515
+ /** Entry file, as a path from the project root. */
1516
+ readonly file: string;
1517
+ /** Absolute project root the exporter resolves `file` and its imports against, when the host has one. */
1518
+ readonly projectPath?: string;
1519
+ readonly format: GeoSpecExportFormat;
1520
+ /** JSON-serialisable parameter values; present only when the exporter declares `parameters`. */
1521
+ readonly parameters?: Readonly<Record<string, unknown>>;
1522
+ /** Tessellation tolerances for a mesh export. */
1523
+ readonly mesh?: {
1524
+ readonly linearTolerance?: number;
1525
+ readonly angularToleranceDegrees?: number;
1526
+ };
1527
+ /** Millimetre crop box; present only when the exporter declares `region`. */
1528
+ readonly region?: GeoSpecLoadRegion;
1529
+ /** Source text keyed by project-relative path; present only when the exporter declares `inlineSources`. */
1530
+ readonly inline?: Readonly<Record<string, string>>;
1531
+ readonly signal?: AbortSignal;
1532
+ }
1533
+
1534
+ // Entry file, as a path from the project root
1535
+ readonly file: string
1536
+
1537
+ // Absolute project root the exporter resolves `file` and its imports against, when the host has one
1538
+ readonly projectPath?: string
1539
+
1540
+ readonly format: GeoSpecExportFormat
1541
+
1542
+ // JSON-serialisable parameter values
1543
+ readonly parameters?: Readonly<Record<string, unknown>>
1544
+
1545
+ // Tessellation tolerances for a mesh export
1546
+ readonly mesh?: {
1547
+ readonly linearTolerance?: number;
1548
+ readonly angularToleranceDegrees?: number;
1549
+ }
1550
+
1551
+ // Millimetre crop box
1552
+ readonly region?: GeoSpecLoadRegion
1553
+
1554
+ // Source text keyed by project-relative path
1555
+ readonly inline?: Readonly<Record<string, string>>
1556
+
1557
+ readonly signal?: AbortSignal
1558
+
1474
1559
  // Geometry formats accepted by {@link import ('./load-model.js').loadModel}
1475
1560
  GeoSpecModelFormat: MeshFileFormat | 'step' | 'stp'
1476
1561
 
1477
1562
  // Function shape used by GeoSpec runners to provide model loading inside VM executed test files
1478
1563
  GeoSpecModelLoader: <Code extends Record<string, string> = Record<string, string>>(options: LoadModelOptions<Code>) => Promise<GeoSpecSubject>
1479
1564
 
1480
- // A configured loader whose shared runtime can be released with its owner
1565
+ // A configured loader whose admissions can be released with its owner
1481
1566
  ManagedGeoSpecModelLoader: GeoSpecModelLoader & {
1482
1567
  dispose(): Promise<void>;
1483
1568
  }
@@ -1485,54 +1570,11 @@ ManagedGeoSpecModelLoader: GeoSpecModelLoader & {
1485
1570
  // ManagedGeoSpecModelLoader.dispose (method)
1486
1571
  dispose(): Promise<void>;
1487
1572
 
1488
- // Runtime client surface consumed by `geospec/model`
1489
- // Remarks: GeoSpec accepts concrete Tau runtime clients from multiple call sites but only needs connection lifecycle and request-scoped documents. Keep this shape small so typed runtime clients do not have to widen their full generic method surface to GeoSpec's testing DSL. A client with `shutdown` is awaited through it when GeoSpec releases an owned runtime, so its host resources are closed before the caller (for example a worker thread) exits. A client with `snapshotSource` lets one run reuse an identical file load after confirming that the source closure it exported is unchanged.
1490
- GeoSpecRuntimeClient: Pick<RuntimeClient, 'connect' | 'terminate'> & Partial<Pick<RuntimeClient, 'shutdown' | 'snapshotSource' | 'describe'>> & {
1491
- open: (input: Pick<Parameters<RuntimeClient['open']>[0], 'source' | 'parameters' | 'stage' | 'watch' | 'signal'>) => Pick<ReturnType<RuntimeClient['open']>, 'export' | 'close'>;
1492
- on?(event: 'telemetry', handler: (batch: {
1493
- readonly entries: ReadonlyArray<{
1494
- name: string;
1495
- duration: number;
1496
- startTime: number;
1497
- workerTimeOrigin: number;
1498
- }>;
1499
- }) => void): () => void;
1500
- }
1501
-
1502
- open: (input: Pick<Parameters<RuntimeClient['open']>[0], 'source' | 'parameters' | 'stage' | 'watch' | 'signal'>) => Pick<ReturnType<RuntimeClient['open']>, 'export' | 'close'>
1503
-
1504
- // GeoSpecRuntimeClient.on (method)
1505
- on?(event: 'telemetry', handler: (batch: {
1506
- readonly entries: ReadonlyArray<{
1507
- name: string;
1508
- duration: number;
1509
- startTime: number;
1510
- workerTimeOrigin: number;
1511
- }>;
1512
- }) => void): () => void;
1513
-
1514
- // Lazy runtime factory consumed by `geospec/model`
1515
- GeoSpecRuntimeClientFactory: () => Promise<GeoSpecRuntimeClient>
1516
-
1517
- // Explicit source adapter for formats whose runtime setup is not part of the generic Tau runtime preset
1518
- GeoSpecRuntimeSourceAdapter: {
1519
- id: string;
1520
- extensions: readonly string[];
1521
- createRuntime(options: {
1522
- projectPath?: string;
1523
- file?: string;
1524
- }): Promise<GeoSpecRuntimeClient>;
1525
- }
1526
-
1527
- id: string
1528
-
1529
- extensions: readonly string[]
1530
-
1531
- // GeoSpecRuntimeSourceAdapter.createRuntime (method)
1532
- createRuntime(options: {
1533
- projectPath?: string;
1534
- file?: string;
1535
- }): Promise<GeoSpecRuntimeClient>;
1573
+ // The source files one export read, each with its SHA-256 or `'missing'`
1574
+ GeoSpecConsumedSources: ReadonlyArray<{
1575
+ readonly path: string;
1576
+ readonly sha256: string;
1577
+ }>
1536
1578
 
1537
1579
  // Inline code-CAD model load options
1538
1580
  LoadModelCodeOptions: {
@@ -1540,15 +1582,13 @@ LoadModelCodeOptions: {
1540
1582
  code: Code;
1541
1583
  /** Entry path to render from {@link code}. */
1542
1584
  file: keyof Code & string;
1585
+ /** Not accepted: inline code has no project folder to resolve in, and a load naming one is refused. */
1586
+ rootDir?: never;
1543
1587
  /** Geometry format to export. Defaults to `glb`. */
1544
1588
  format?: GeoSpecModelFormat;
1545
- /** Explicit parameters passed to the runtime. */
1589
+ /** Explicit parameters passed to the exporter. */
1546
1590
  parameters?: Record<string, unknown>;
1547
- /** Runtime client or lazy runtime factory. */
1548
- runtime?: GeoSpecRuntimeClient | GeoSpecRuntimeClientFactory;
1549
- /** Source-specific runtime adapters, e.g. host-provided GPL-isolated kernels. */
1550
- sourceAdapters?: readonly GeoSpecRuntimeSourceAdapter[];
1551
- /** Project root used by runtime integrations. */
1591
+ /** Absolute project root passed to the exporter. */
1552
1592
  projectPath?: string;
1553
1593
  /** STEP reader strategy used for STEP exports. */
1554
1594
  stepStreaming?: StepStreamingMode;
@@ -1565,12 +1605,11 @@ LoadModelCodeOptions: {
1565
1605
  */
1566
1606
  workUnitLimit?: number;
1567
1607
  /**
1568
- * Axis-aligned millimetre box the kernel crops the model to before export, so a large mesh model
1569
- * can be checked region by region. Only kernels whose direct GLB export declares a `region` option
1570
- * honor it; any other kernel, a STEP load or a crop the kernel does not confirm refuses with a typed
1571
- * diagnostic instead of loading the whole model. The cropped subject is a different subject: its
1572
- * admission carries the kernel's crop notice and its load evidence records `region`, so a claim on
1573
- * it never stands for the whole model.
1608
+ * Axis-aligned millimetre box the exporter crops the model to before export, so a large mesh model
1609
+ * can be checked region by region. Only an exporter that declares `region` honours it; any other
1610
+ * exporter, or a crop the exporter cannot make, refuses with a typed diagnostic instead of loading
1611
+ * the whole model. The cropped subject is a different subject: its load evidence records `region`,
1612
+ * so a claim on it never stands for the whole model.
1574
1613
  */
1575
1614
  region?: GeoSpecLoadRegion;
1576
1615
  }
@@ -1581,19 +1620,16 @@ LoadModelCodeOptions: {
1581
1620
  // Entry path to render from {@link code }
1582
1621
  file: keyof Code & string
1583
1622
 
1623
+ // Not accepted
1624
+ rootDir?: never
1625
+
1584
1626
  // Geometry format to export
1585
1627
  format?: GeoSpecModelFormat
1586
1628
 
1587
- // Explicit parameters passed to the runtime
1629
+ // Explicit parameters passed to the exporter
1588
1630
  parameters?: Record<string, unknown>
1589
1631
 
1590
- // Runtime client or lazy runtime factory
1591
- runtime?: GeoSpecRuntimeClient | GeoSpecRuntimeClientFactory
1592
-
1593
- // Source-specific runtime adapters, e.g
1594
- sourceAdapters?: readonly GeoSpecRuntimeSourceAdapter[]
1595
-
1596
- // Project root used by runtime integrations
1632
+ // Absolute project root passed to the exporter
1597
1633
  projectPath?: string
1598
1634
 
1599
1635
  // STEP reader strategy used for STEP exports
@@ -1611,23 +1647,28 @@ LoadModelCodeOptions: {
1611
1647
  // Default work-unit budget for every claim on this subject
1612
1648
  workUnitLimit?: number
1613
1649
 
1614
- // Axis-aligned millimetre box the kernel crops the model to before export, so a large mesh model can be checked region by region
1650
+ // Axis-aligned millimetre box the exporter crops the model to before export, so a large mesh model can be checked region by region
1615
1651
  region?: GeoSpecLoadRegion
1616
1652
 
1617
1653
  // Filesystem-backed model load options
1618
1654
  LoadModelFileOptions: {
1619
- /** Project-relative model file to render. */
1655
+ /**
1656
+ * Model file to render, as a path from the project root: the same root every tool's `targetFile` resolves
1657
+ * against, which the result names as `projectRoot` where the host reports it, as `tau mcp` does.
1658
+ */
1620
1659
  file: string;
1621
- /** Project root used by runtime integrations. */
1660
+ /**
1661
+ * Project-relative folder `file` resolves in, for a suite that loads from somewhere other than the project root:
1662
+ * `loadModel({ file: 'main.ts', rootDir: 'parts/gear' })` loads `parts/gear/main.ts`. Recorded in the load
1663
+ * evidence.
1664
+ */
1665
+ rootDir?: string;
1666
+ /** Absolute project root passed to the exporter. */
1622
1667
  projectPath?: string;
1623
1668
  /** Geometry format to export. Defaults to `glb`. */
1624
1669
  format?: GeoSpecModelFormat;
1625
- /** Explicit parameters passed to the runtime. */
1670
+ /** Explicit parameters passed to the exporter. */
1626
1671
  parameters?: Record<string, unknown>;
1627
- /** Runtime client or lazy runtime factory. */
1628
- runtime?: GeoSpecRuntimeClient | GeoSpecRuntimeClientFactory;
1629
- /** Source-specific runtime adapters, e.g. host-provided GPL-isolated kernels. */
1630
- sourceAdapters?: readonly GeoSpecRuntimeSourceAdapter[];
1631
1672
  /** STEP reader strategy used for STEP exports. */
1632
1673
  stepStreaming?: StepStreamingMode;
1633
1674
  /** Whether STEP loading should also produce mesh evidence. Defaults to true. */
@@ -1643,34 +1684,30 @@ LoadModelFileOptions: {
1643
1684
  */
1644
1685
  workUnitLimit?: number;
1645
1686
  /**
1646
- * Axis-aligned millimetre box the kernel crops the model to before export, so a large mesh model
1647
- * can be checked region by region. Only kernels whose direct GLB export declares a `region` option
1648
- * honor it; any other kernel, a STEP load or a crop the kernel does not confirm refuses with a typed
1649
- * diagnostic instead of loading the whole model. The cropped subject is a different subject: its
1650
- * admission carries the kernel's crop notice and its load evidence records `region`, so a claim on
1651
- * it never stands for the whole model.
1687
+ * Axis-aligned millimetre box the exporter crops the model to before export, so a large mesh model
1688
+ * can be checked region by region. Only an exporter that declares `region` honours it; any other
1689
+ * exporter, or a crop the exporter cannot make, refuses with a typed diagnostic instead of loading
1690
+ * the whole model. The cropped subject is a different subject: its load evidence records `region`,
1691
+ * so a claim on it never stands for the whole model.
1652
1692
  */
1653
1693
  region?: GeoSpecLoadRegion;
1654
1694
  }
1655
1695
 
1656
- // Project-relative model file to render
1696
+ // Model file to render, as a path from the project root
1657
1697
  file: string
1658
1698
 
1659
- // Project root used by runtime integrations
1699
+ // Project-relative folder `file` resolves in, for a suite that loads from somewhere other than the project root
1700
+ rootDir?: string
1701
+
1702
+ // Absolute project root passed to the exporter
1660
1703
  projectPath?: string
1661
1704
 
1662
1705
  // Geometry format to export
1663
1706
  format?: GeoSpecModelFormat
1664
1707
 
1665
- // Explicit parameters passed to the runtime
1708
+ // Explicit parameters passed to the exporter
1666
1709
  parameters?: Record<string, unknown>
1667
1710
 
1668
- // Runtime client or lazy runtime factory
1669
- runtime?: GeoSpecRuntimeClient | GeoSpecRuntimeClientFactory
1670
-
1671
- // Source-specific runtime adapters, e.g
1672
- sourceAdapters?: readonly GeoSpecRuntimeSourceAdapter[]
1673
-
1674
1711
  // STEP reader strategy used for STEP exports
1675
1712
  stepStreaming?: StepStreamingMode
1676
1713
 
@@ -1686,16 +1723,19 @@ LoadModelFileOptions: {
1686
1723
  // Default work-unit budget for every claim on this subject
1687
1724
  workUnitLimit?: number
1688
1725
 
1689
- // Axis-aligned millimetre box the kernel crops the model to before export, so a large mesh model can be checked region by region
1726
+ // Axis-aligned millimetre box the exporter crops the model to before export, so a large mesh model can be checked region by region
1690
1727
  region?: GeoSpecLoadRegion
1691
1728
 
1692
1729
  // Options accepted by {@link import ('./load-model.js').loadModel}
1693
1730
  LoadModelOptions: LoadModelSourceOptions | LoadModelCodeOptions<Code> | LoadModelFileOptions
1694
1731
 
1732
+ // Project-relative folder `file` resolves in, for a suite that loads from somewhere other than the project root
1733
+ rootDir?: string
1734
+
1695
1735
  // Geometry format to export
1696
1736
  format?: GeoSpecModelFormat
1697
1737
 
1698
- // Explicit parameters passed to the runtime
1738
+ // Explicit parameters passed to the exporter
1699
1739
  parameters?: Record<string, unknown>
1700
1740
 
1701
1741
  // STEP reader strategy used for STEP exports
@@ -1722,6 +1762,11 @@ LoadModelSourceOptions: {
1722
1762
  readonly name: string;
1723
1763
  readonly source: MeshSource | StepSource;
1724
1764
  }>;
1765
+ /**
1766
+ * Project-relative folder a path `source` and each resource path resolve in. Omitted, they resolve against the
1767
+ * project root. Recorded in the load evidence.
1768
+ */
1769
+ rootDir?: string;
1725
1770
  /** Source geometry format. Defaults to `glb`. */
1726
1771
  format?: GeoSpecModelFormat;
1727
1772
  /** Source path recorded in provenance. */
@@ -1757,6 +1802,9 @@ LoadModelSourceOptions: {
1757
1802
  readonly source: MeshSource | StepSource;
1758
1803
  }>
1759
1804
 
1805
+ // Project-relative folder a path `source` and each resource path resolve in
1806
+ rootDir?: string
1807
+
1760
1808
  // Source geometry format
1761
1809
  format?: GeoSpecModelFormat
1762
1810
 
@@ -1,6 +1,6 @@
1
1
  # geospec — Functions
2
2
 
3
- 36 top-level symbols. Signatures are verbatim typescript.
3
+ 39 top-level symbols. Signatures are verbatim typescript.
4
4
 
5
5
  // GeoSpec suite helper used inside VM-executed test modules
6
6
  // describe (function)
@@ -67,20 +67,11 @@ export declare function createModelLoader(defaults: CreateModelLoaderOptions): M
67
67
  export declare function loadModel<Code extends Record<string, string> = Record<string, string>>(_options: LoadModelOptions<Code>): Promise<GeoSpecSubject>;
68
68
  // _options: Source, code, or file model load options
69
69
 
70
- // resolveRuntimeExportIntent (function)
71
- export declare function resolveRuntimeExportIntent(options: {
72
- runtime: GeoSpecRuntimeClient;
73
- format: RuntimeBackedModelFormat;
74
- meshLinearTolerance?: number;
75
- meshAngularToleranceDegrees?: number;
76
- /**
77
- * The kernel that evaluates this source, when the host knows it. Routes are
78
- * then chosen among that kernel's own, so a mesh-only kernel is told its
79
- * BRep matchers are unsupported instead of being sent to another kernel's
80
- * STEP route.
81
- */
82
- kernelId?: string;
83
- }): RuntimeExportIntent | RuntimeExportIntentFailure;
70
+ // Create a model exporter that runs a command speaking GeoSpec subprocess protocol 1
71
+ // Throws: TypeError when the options are incomplete or declare `inlineSources`.
72
+ // commandExporter (function)
73
+ export declare function commandExporter(options: CommandExporterOptions): GeoSpecModelExporter;
74
+ // options: The exporter's identity, command and declared capabilities
84
75
 
85
76
  // clearCollectorGlobals (function)
86
77
  export declare function clearCollectorGlobals(): void;
@@ -155,12 +146,34 @@ export declare function allocateNativePoolGrants(options: {
155
146
  // Create a native model loader that admits actual STEP/GLB bytes and retains generation-checked handles until the owning runner finishes
156
147
  // createGeoSpecNativeModelLoader (function)
157
148
  export declare function createGeoSpecNativeModelLoader(defaults: CreateGeoSpecNativeModelLoaderOptions): ManagedGeoSpecNativeModelLoader;
158
- // defaults: Native engine, Runtime defaults, and optional source reader
149
+ // defaults: Native engine, exporters, and optional source reader
150
+
151
+ // Create a Node `VmFileSystem` rooted at `root`
152
+ // createNodeVmFileSystem (function)
153
+ export declare function createNodeVmFileSystem(root: string): VmFileSystem;
154
+ // root: Absolute project root path
155
+
156
+ // Resolve one VM path to a real path under the root
157
+ // Throws: Error when the path escapes the root.
158
+ // resolveUnderRoot (function)
159
+ export declare function resolveUnderRoot(root: string, path: string): string;
160
+ // root: The project root
161
+ // path: A canonical path rooted by the supplied project capability
159
162
 
160
163
  // Create a run-level issue when filters select no tests
161
164
  // createNoMatchingGeoSpecTestsIssue (function)
162
165
  export declare function createNoMatchingGeoSpecTestsIssue(): VmIssue;
163
166
 
167
+ // Create the host-agnostic pool runner
168
+ // createGeoSpecPoolRunner (function)
169
+ export declare function createGeoSpecPoolRunner(options: GeoSpecPoolOptions): GeoSpecRunner;
170
+ // options: Worker factory, worker count, telemetry and event hook
171
+
172
+ // Serve shards until the host says shutdown
173
+ // startGeoSpecPoolWorkerHost (function)
174
+ export declare function startGeoSpecPoolWorkerHost(options: GeoSpecPoolWorkerHostOptions): void;
175
+ // options: Worker filesystem, native engine, and message plumbing
176
+
164
177
  // Create a standalone native GeoSpec assertion client
165
178
  // createGeoSpecAssertionClient (function)
166
179
  export declare function createGeoSpecAssertionClient(options: GeoSpecAssertionClientOptions): GeoSpecAssertionClient;
@@ -202,12 +215,6 @@ export declare function installGeoSpecVitest(client: GeoSpecAssertionClient): Ge
202
215
  export declare function setupGeoSpecVitest(options: GeoSpecAssertionClientOptions): GeoSpecVitestAdapter;
203
216
  // options: Flat native assertion-client options
204
217
 
205
- // Export one Tau project from Runtime's coherent source snapshot
206
- // Remarks: This helper preserves finalized bytes and provenance metadata. It does not certify mathematical geometry or grant the runtime trusted-evaluator authority.
207
- // exportTauProjectArtifact (function)
208
- export declare function exportTauProjectArtifact(options: ExportTauProjectArtifactOptions): Promise<KernelResult<GeoSpecTauProjectArtifact>>;
209
- // options: Descriptor, fresh-runtime factory, and optional cancellation signal
210
-
211
218
  // Load one trusted project config using Node's native module loader
212
219
  // Remarks: Explicit selection or exactly one geospec.config.js/.mjs/.ts/.mts is allowed. TypeScript must use erasable syntax; JSON imports use standard attributes. Executable config/imports are trusted developer code, not sandboxed code. Node's same-process module cache is unchanged: load once per run and use a fresh process when fresh executable imports are required. No reload guarantee or transitive-source identity is supplied here.
213
220
  // loadGeoSpecConfig (function)