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

package/README.md

@@ -68,14 +68,47 @@ qualification, and filtered requirements remain outside the demonstrated scope.
 
 ### Runner configuration
 
-Install [`@taucad/geospec-engine`](../geospec-engine) for its `geospec` CLI or
-Node worker pool. To embed a serial runner, pass a compiled engine to
-`createNativeGeoSpecRunner` from `geospec/runner/native`; it builds the native
-model loader and releases every admitted subject after each run. These use the
-same compiled composition. Other embeddings must qualify their actual binding,
-input representation and supported domain; shared authoring syntax alone does
-not establish verdict equivalence. The CLI's flags and pool options are
-documented in that package's README.
+The `geospec` bin runs a project's specs on the compiled engine from
+[`geospec-engine`](https://github.com/taucad/geospec/tree/main/packages/geospec-engine):
+the native addon when this platform has one, else its WASM build. Models that
+are not STEP or GLB come from the `exporters` the project's `geospec.config.*`
+declares, imported once in each pool worker; without one, such a load refuses
+with `GEOSPEC_EXPORTER_MISSING`.
+
+```bash
+geospec run .
+geospec run . --include "parts/**/*.geospec.ts"
+geospec run . --file main.geospec.ts --test-name-pattern volume
+geospec run . --workers            # worker pool, auto-sized
+geospec run . --workers 4 --shard-timeout 600000
+geospec run . --config ci.geospec.config.ts
+geospec run . --json
+```
+
+| Flag                                    | Meaning                                                                                                   |
+| --------------------------------------- | --------------------------------------------------------------------------------------------------------- |
+| `--file <path>`                         | GeoSpec file or directory root; repeatable. Empty input discovers from the project root.                  |
+| `--include <glob>` / `--exclude <glob>` | Vitest-style file globs; repeatable. Include defaults to `**/*.geospec.{ts,js}`.                          |
+| `-t`, `--test-name-pattern <re>`        | JavaScript regular expression matched against the full `suite > test` name.                               |
+| `--test-timeout <ms>`                   | Timeout for each async test callback.                                                                     |
+| `--workers [n]`                         | Run in a worker pool. Default is one; omit the count after the flag to request available CPU parallelism. |
+| `--shard-timeout <ms>`                  | Per-shard **non-verdict** watchdog. Off by default.                                                       |
+| `--bail`                                | Stop after the first red file. Interactive use only — a reward run wants the complete red set.            |
+| `--config <path>`                       | The `geospec.config.*` to use instead of the one in the project root.                                     |
+| `--json`                                | Print exactly one JSON result document on stdout and nothing else.                                        |
+
+A flag replaces the config field of the same name. **The exit code is the
+verdict.** `0` only when the run succeeded; any failure, any run-level issue,
+and an empty selection are all `1`.
+
+To embed the pool, use `createGeoSpecNodePoolRunner` from `geospec/runner/node`;
+each worker owns one engine and its own exporters, and live subjects never
+cross worker boundaries. To run serially in this process, pass an engine from
+`createNodeGeoSpecEngine` to `createNativeGeoSpecRunner` from
+`geospec/runner/native`; it builds the native model loader and releases every
+admitted subject after each run. Other embeddings must qualify their actual
+binding, input representation and supported domain; shared authoring syntax
+alone does not establish verdict equivalence.
 
 The filters below are the shared vocabulary of the CLI, the embedded runners
 and the Tau `test_model` tool:

package/agent/geospec-authoring/SKILL.md

@@ -106,7 +106,7 @@ LoadModelOptions: LoadModelSourceOptions | LoadModelCodeOptions<Code> | LoadMode
   rootDir?: string
   // Geometry format to export
   format?: GeoSpecModelFormat
-  // Explicit parameters passed to the runtime
+  // Explicit parameters passed to the exporter
   parameters?: Record<string, unknown>
   // STEP reader strategy used for STEP exports
   stepStreaming?: StepStreamingMode
@@ -129,6 +129,10 @@ export declare function it(name: string, function_: GeoSpecTestCallback): void;
 // GeoSpec suite helper used inside VM-executed test modules
 export declare function describe(name: string, function_: GeoSpecTestCallback): void;
   skip(name: string, function_?: GeoSpecTestCallback): void;
+
+// Alias for {@link it}
+export declare function test(name: string, function_: GeoSpecTestCallback): void;
+  skip(name: string, function_?: GeoSpecTestCallback): void;
 ```
 
 ### Types
@@ -467,29 +471,26 @@ GeoSpecVoidWaypoint: Vec3 | {
     occurrence: string;
 }
 
-// Inline code-CAD model load options
-LoadModelCodeOptions: {
-  // Source files keyed by project-relative path
-  code: Code
-  // Geometry format to export
+// Direct geometry-source model load options
+LoadModelSourceOptions: {
+  // Source geometry format
   format?: GeoSpecModelFormat
-  // Explicit parameters passed to the runtime
+  // Explicit parameters recorded in provenance
   parameters?: Record<string, unknown>
   // Whether STEP loading should also produce mesh evidence
   mesh?: boolean
-  // … 10 more members in the API reference: file, rootDir, runtime, sourceAdapters, projectPath, stepStreaming, meshLinearTolerance, meshAngularToleranceDegrees, workUnitLimit, region
+  // … 10 more members in the API reference: source, resources, rootDir, path, name, sourceUnit, stepStreaming, meshLinearTolerance, meshAngularToleranceDegrees, workUnitLimit
 }
-
-RuntimeBackedModelFormat: Exclude<GeoSpecModelFormat, 'mesh-buffer'>
 ```
 
 ## API reference
 
-To read any other signature, find its name in `api-index.md`, which lists all 364 symbols by file with the lines that hold each, and read that range of the named file.
+To read any other signature, find its name in `api-index.md`, which lists all 368 symbols by file with the lines that hold each, and read that range of the named file.
 
 - `api-functions.md` — Functions
 - `api-constants.md` — Constants
 - `api-types.md` — Types
+- `api-types-2.md` — Types (2)
 - `api-classes.md` — Classes
 
 Read ranges, not whole files. Never copy a reference into a source file.

package/agent/geospec-authoring/api-functions.md

@@ -1,6 +1,6 @@
 # geospec — Functions
 
-7 top-level symbols. Signatures are verbatim typescript.
+6 top-level symbols. Signatures are verbatim typescript.
 
 // GeoSpec suite helper used inside VM-executed test modules
 // describe (function)
@@ -40,18 +40,3 @@ export declare function createModelLoader(defaults: CreateModelLoaderOptions): M
 // loadModel (function)
 export declare function loadModel<Code extends Record<string, string> = Record<string, string>>(_options: LoadModelOptions<Code>): Promise<GeoSpecSubject>;
 //   _options: Source, code, or file model load options
-
-// resolveRuntimeExportIntent (function)
-export declare function resolveRuntimeExportIntent(options: {
-    runtime: GeoSpecRuntimeClient;
-    format: RuntimeBackedModelFormat;
-    meshLinearTolerance?: number;
-    meshAngularToleranceDegrees?: number;
-    /**
-     * The kernel that evaluates this source, when the host knows it. Routes are
-     * then chosen among that kernel's own, so a mesh-only kernel is told its
-     * BRep matchers are unsupported instead of being sent to another kernel's
-     * STEP route.
-     */
-    kernelId?: string;
-}): RuntimeExportIntent | RuntimeExportIntentFailure;

package/agent/geospec-authoring/api-index.md

@@ -1,6 +1,6 @@
 # geospec API index
 
-geospec 0.1.0-beta.7 · 364 symbols · extracted by TypeScript 5.9.3.
+geospec 0.1.0-beta.9 · 368 symbols · extracted by TypeScript 5.9.3.
 
 Every symbol appears here exactly once. The heading above each block names the file with its signature, and each top-level symbol names the lines of that file which hold its declaration and members: read only that range.
 
@@ -15,7 +15,6 @@ test (function) [lines 25-30] [1 members] — Alias for {@link it}
   test.skip (method)
 createModelLoader (function) [lines 32-35] — Create a {@link loadModel} function over a host-supplied compiled engine
 loadModel (function) [lines 37-42] — Load a CAD model into GeoSpec evidence
-resolveRuntimeExportIntent (function) [lines 44-57]
 
 ## Constants — `api-constants.md`
 
@@ -282,84 +281,92 @@ StepEvidence (type) [lines 1288-1338] [6 members] — STEP/XDE evidence extracte
   StepEvidence.xde (property) — Structured AP242 XDE read result (occurrences, subshape names, datum placements)
 Vec3 (type) [lines 1340-1341] — Numeric 3D vector
 GeoSpecVec3 (type) [lines 1343-1344] — Numeric 3D vector
-GeoSpecExportRoute (type) [lines 1346-1359] — Runtime route metadata used to decide whether a runtime export…
-RuntimeBackedModelFormat (type) [lines 1361-1361]
-RuntimeClientWithRoutes (type) [lines 1363-1385] [3 members] — Runtime client shape for route-aware Tau runtimes
-  RuntimeClientWithRoutes.open (property)
-  RuntimeClientWithRoutes.on (method)
-  RuntimeClientWithRoutes.bestRouteFor (method)
-RuntimeExportIntent (type) [lines 1387-1398] [3 members] — Resolved runtime export request and provenance for a GeoSpec model…
-  RuntimeExportIntent.options (property)
-  RuntimeExportIntent.provenance (property)
-  RuntimeExportIntent.sourceUnit (property)
-RuntimeExportIntentFailure (type) [lines 1400-1408] [2 members] — Structured failure returned when a runtime cannot provide the requested…
-  RuntimeExportIntentFailure.success (property)
-  RuntimeExportIntentFailure.diagnostics (property)
-CreateModelLoaderOptions (type) [lines 1410-1462] [10 members] — Defaults accepted by {@link import ('./load-model.js').createModelLoader}
+CreateModelLoaderOptions (type) [lines 1346-1393] [9 members] — Defaults accepted by {@link import ('./load-model.js').createModelLoader}
   CreateModelLoaderOptions.engine (property) — Initialized compiled engine supplied by the host, never selected by…
   CreateModelLoaderOptions.readSource (property) — Rooted host reader for direct filesystem or URL sources
   CreateModelLoaderOptions.format (property) — Geometry format to export when an individual call does not…
-  CreateModelLoaderOptions.runtime (property) — Runtime client or lazy runtime factory
-  CreateModelLoaderOptions.sourceAdapters (property) — Source-specific runtime adapters, e.g
-  CreateModelLoaderOptions.projectPath (property) — Project root used by runtime integrations
+  CreateModelLoaderOptions.exporters (property) — Model exporters for source-kind files
+  CreateModelLoaderOptions.projectPath (property) — Absolute project root passed to the exporter
   CreateModelLoaderOptions.stepStreaming (property) — STEP reader strategy used for STEP sources or exports
   CreateModelLoaderOptions.mesh (property) — Whether STEP loading should also produce mesh evidence
   CreateModelLoaderOptions.meshLinearTolerance (property) — Linear tolerance used while meshing exact BRep evidence
   CreateModelLoaderOptions.meshAngularToleranceDegrees (property) — Angular tolerance in degrees used while meshing exact BRep evidence
-GeoSpecLoadRegion (type) [lines 1464-1472] [2 members] — Axis-aligned crop box in canonical Z-up millimetres
+GeoSpecExporterCapabilities (type) [lines 1395-1417] [4 members] — What a {@link GeoSpecModelExporter} declares it can do
+  GeoSpecExporterCapabilities.formats (property) — The formats `export` produces
+  GeoSpecExporterCapabilities.parameters (property) — Accepts `parameters`
+  GeoSpecExporterCapabilities.region (property) — Crops to `region` (an axis-aligned millimetre box) before export
+  GeoSpecExporterCapabilities.inlineSources (property) — Accepts `inline` sources, which back `loadModel({ code })`
+GeoSpecExportFormat (type) [lines 1419-1420] — Formats a {@link GeoSpecModelExporter} may produce from a source-kind file
+GeoSpecLoadRegion (type) [lines 1422-1430] [2 members] — Axis-aligned crop box in canonical Z-up millimetres
   GeoSpecLoadRegion.min (property)
   GeoSpecLoadRegion.max (property)
-GeoSpecModelFormat (type) [lines 1474-1475] — Geometry formats accepted by {@link import ('./load-model.js').loadModel}
-GeoSpecModelLoader (type) [lines 1477-1478] — Function shape used by GeoSpec runners to provide model loading…
-ManagedGeoSpecModelLoader (type) [lines 1480-1486] [1 members] — A configured loader whose shared runtime can be released with…
+GeoSpecModelArtifact (type) [lines 1432-1475] [7 members] — The bytes an exporter returns, in the canonical Z-up millimetre…
+  GeoSpecModelArtifact.bytes (property)
+  GeoSpecModelArtifact.format (property)
+  GeoSpecModelArtifact.sourceUnit (property) — Unit of raw GLB coordinates
+  GeoSpecModelArtifact.resources (property) — External resources the primary bytes reference, by name
+  GeoSpecModelArtifact.consumedSources (property) — Every source file the export read, as a path from…
+  GeoSpecModelArtifact.diagnostics (property) — Notices from a successful export, admitted with the subject so…
+  GeoSpecModelArtifact.exportOptions (property) — The export options the exporter applied, recorded in the load…
+GeoSpecModelExporter (type) [lines 1477-1511] [6 members] — Turns a source-kind model file into GLB or STEP bytes…
+  GeoSpecModelExporter.id (property)
+  GeoSpecModelExporter.extensions (property)
+  GeoSpecModelExporter.capabilities (property)
+  GeoSpecModelExporter.export (method)
+  GeoSpecModelExporter.revision (method) — The sources an export of `file` would read now, without…
+  GeoSpecModelExporter.close (method) — Releases what the exporter created for one scope
+GeoSpecModelExportRequest (type) [lines 1513-1557] [8 members] — One export request
+  GeoSpecModelExportRequest.file (property) — Entry file, as a path from the project root
+  GeoSpecModelExportRequest.projectPath (property) — Absolute project root the exporter resolves `file` and its imports…
+  GeoSpecModelExportRequest.format (property)
+  GeoSpecModelExportRequest.parameters (property) — JSON-serialisable parameter values
+  GeoSpecModelExportRequest.mesh (property) — Tessellation tolerances for a mesh export
+  GeoSpecModelExportRequest.region (property) — Millimetre crop box
+  GeoSpecModelExportRequest.inline (property) — Source text keyed by project-relative path
+  GeoSpecModelExportRequest.signal (property)
+GeoSpecModelFormat (type) [lines 1559-1560] — Geometry formats accepted by {@link import ('./load-model.js').loadModel}
+GeoSpecModelLoader (type) [lines 1562-1563] — Function shape used by GeoSpec runners to provide model loading…
+ManagedGeoSpecModelLoader (type) [lines 1565-1571] [1 members] — A configured loader whose admissions can be released with its…
   ManagedGeoSpecModelLoader.dispose (method)
-GeoSpecRuntimeClient (type) [lines 1488-1512] [2 members] — Runtime client surface consumed by `geospec/model`
-  GeoSpecRuntimeClient.open (property)
-  GeoSpecRuntimeClient.on (method)
-GeoSpecRuntimeClientFactory (type) [lines 1514-1515] — Lazy runtime factory consumed by `geospec/model`
-GeoSpecRuntimeSourceAdapter (type) [lines 1517-1535] [3 members] — Explicit source adapter for formats whose runtime setup is not…
-  GeoSpecRuntimeSourceAdapter.id (property)
-  GeoSpecRuntimeSourceAdapter.extensions (property)
-  GeoSpecRuntimeSourceAdapter.createRuntime (method)
-LoadModelCodeOptions (type) [lines 1537-1620] [14 members] — Inline code-CAD model load options
+GeoSpecConsumedSources (type) [lines 1573-1577] — The source files one export read, each with its SHA-256…
+LoadModelCodeOptions (type) [lines 1579-1651] [12 members] — Inline code-CAD model load options
   LoadModelCodeOptions.code (property) — Source files keyed by project-relative path
   LoadModelCodeOptions.file (property) — Entry path to render from {@link code }
   LoadModelCodeOptions.rootDir (property) — Not accepted
   LoadModelCodeOptions.format (property) — Geometry format to export
-  LoadModelCodeOptions.parameters (property) — Explicit parameters passed to the runtime
-  LoadModelCodeOptions.runtime (property) — Runtime client or lazy runtime factory
-  LoadModelCodeOptions.sourceAdapters (property) — Source-specific runtime adapters, e.g
-  LoadModelCodeOptions.projectPath (property) — Project root used by runtime integrations
+  LoadModelCodeOptions.parameters (property) — Explicit parameters passed to the exporter
+  LoadModelCodeOptions.projectPath (property) — Absolute project root passed to the exporter
   LoadModelCodeOptions.stepStreaming (property) — STEP reader strategy used for STEP exports
   LoadModelCodeOptions.mesh (property) — Whether STEP loading should also produce mesh evidence
   LoadModelCodeOptions.meshLinearTolerance (property) — Linear tolerance used while meshing exact BRep evidence
   LoadModelCodeOptions.meshAngularToleranceDegrees (property) — Angular tolerance in degrees used while meshing exact BRep evidence
   LoadModelCodeOptions.workUnitLimit (property) — Default work-unit budget for every claim on this subject
-  LoadModelCodeOptions.region (property) — Axis-aligned millimetre box the kernel crops the model to before…
-LoadModelFileOptions (type) [lines 1622-1707] [13 members] — Filesystem-backed model load options
+  LoadModelCodeOptions.region (property) — Axis-aligned millimetre box the exporter crops the model to before…
+LoadModelFileOptions (type) [lines 1653-1727] [11 members] — Filesystem-backed model load options
   LoadModelFileOptions.file (property) — Model file to render, as a path from the project…
   LoadModelFileOptions.rootDir (property) — Project-relative folder `file` resolves in, for a suite that loads…
-  LoadModelFileOptions.projectPath (property) — Project root used by runtime integrations
+  LoadModelFileOptions.projectPath (property) — Absolute project root passed to the exporter
   LoadModelFileOptions.format (property) — Geometry format to export
-  LoadModelFileOptions.parameters (property) — Explicit parameters passed to the runtime
-  LoadModelFileOptions.runtime (property) — Runtime client or lazy runtime factory
-  LoadModelFileOptions.sourceAdapters (property) — Source-specific runtime adapters, e.g
+  LoadModelFileOptions.parameters (property) — Explicit parameters passed to the exporter
   LoadModelFileOptions.stepStreaming (property) — STEP reader strategy used for STEP exports
   LoadModelFileOptions.mesh (property) — Whether STEP loading should also produce mesh evidence
   LoadModelFileOptions.meshLinearTolerance (property) — Linear tolerance used while meshing exact BRep evidence
   LoadModelFileOptions.meshAngularToleranceDegrees (property) — Angular tolerance in degrees used while meshing exact BRep evidence
   LoadModelFileOptions.workUnitLimit (property) — Default work-unit budget for every claim on this subject
-  LoadModelFileOptions.region (property) — Axis-aligned millimetre box the kernel crops the model to before…
-LoadModelOptions (type) [lines 1709-1734] [8 members] — Options accepted by {@link import ('./load-model.js').loadModel}
+  LoadModelFileOptions.region (property) — Axis-aligned millimetre box the exporter crops the model to before…
+LoadModelOptions (type) [lines 1729-1754] [8 members] — Options accepted by {@link import ('./load-model.js').loadModel}
   LoadModelOptions.rootDir (property) — Project-relative folder `file` resolves in, for a suite that loads…
   LoadModelOptions.format (property) — Geometry format to export
-  LoadModelOptions.parameters (property) — Explicit parameters passed to the runtime
+  LoadModelOptions.parameters (property) — Explicit parameters passed to the exporter
   LoadModelOptions.stepStreaming (property) — STEP reader strategy used for STEP exports
   LoadModelOptions.mesh (property) — Whether STEP loading should also produce mesh evidence
   LoadModelOptions.meshLinearTolerance (property) — Linear tolerance used while meshing exact BRep evidence
   LoadModelOptions.meshAngularToleranceDegrees (property) — Angular tolerance in degrees used while meshing exact BRep evidence
   LoadModelOptions.workUnitLimit (property) — Default work-unit budget for every claim on this subject
-LoadModelSourceOptions (type) [lines 1736-1816] [13 members] — Direct geometry-source model load options
+
+## Types (2) — `api-types-2.md`
+
+LoadModelSourceOptions (type) [lines 5-85] [13 members] — Direct geometry-source model load options
   LoadModelSourceOptions.source (property) — Geometry bytes, path, browser file/blob, or in-memory mesh buffer
   LoadModelSourceOptions.resources (property) — Named external resources consumed alongside the direct geometry bytes
   LoadModelSourceOptions.rootDir (property) — Project-relative folder a path `source` and each resource path resolve…

package/agent/geospec-authoring/api-types-2.md

@@ -0,0 +1,85 @@
+# geospec — Types (2)
+
+1 top-level symbols. Signatures are verbatim typescript.
+
+// Direct geometry-source model load options
+LoadModelSourceOptions: {
+    /** Geometry bytes, path, browser file/blob, or in-memory mesh buffer. */
+    source: MeshSource | StepSource;
+    /** Named external resources consumed alongside the direct geometry bytes. */
+    resources?: ReadonlyArray<{
+        readonly name: string;
+        readonly source: MeshSource | StepSource;
+    }>;
+    /**
+     * Project-relative folder a path `source` and each resource path resolve in. Omitted, they resolve against the
+     * project root. Recorded in the load evidence.
+     */
+    rootDir?: string;
+    /** Source geometry format. Defaults to `glb`. */
+    format?: GeoSpecModelFormat;
+    /** Source path recorded in provenance. */
+    path?: string;
+    /** Human-readable source name recorded in provenance. */
+    name?: string;
+    /** Coordinate unit of raw GLB/glTF or mesh-buffer data before canonical millimetre normalization. */
+    sourceUnit?: GeoSpecUnit;
+    /** Explicit parameters recorded in provenance. */
+    parameters?: Record<string, unknown>;
+    /** STEP reader strategy used for STEP sources. */
+    stepStreaming?: StepStreamingMode;
+    /** Whether STEP loading should also produce mesh evidence. Defaults to true. */
+    mesh?: boolean;
+    /** Linear tolerance used while meshing exact BRep evidence. */
+    meshLinearTolerance?: number;
+    /** Angular tolerance in degrees used while meshing exact BRep evidence. */
+    meshAngularToleranceDegrees?: number;
+    /**
+     * Default work-unit budget for every claim on this subject: a positive integer no greater than
+     * the host's maximum (default `geoSpecMaximumWorkUnitLimit`, 512 000 000). `expectGeo(subject, { workUnitLimit })` overrides
+     * it per chain. Recorded in the load evidence; it never changes the exported or admitted bytes.
+     */
+    workUnitLimit?: number;
+}
+
+  // Geometry bytes, path, browser file/blob, or in-memory mesh buffer
+  source: MeshSource | StepSource
+
+  // Named external resources consumed alongside the direct geometry bytes
+  resources?: ReadonlyArray<{
+          readonly name: string;
+          readonly source: MeshSource | StepSource;
+      }>
+
+  // Project-relative folder a path `source` and each resource path resolve in
+  rootDir?: string
+
+  // Source geometry format
+  format?: GeoSpecModelFormat
+
+  // Source path recorded in provenance
+  path?: string
+
+  // Human-readable source name recorded in provenance
+  name?: string
+
+  // Coordinate unit of raw GLB/glTF or mesh-buffer data before canonical millimetre normalization
+  sourceUnit?: GeoSpecUnit
+
+  // Explicit parameters recorded in provenance
+  parameters?: Record<string, unknown>
+
+  // STEP reader strategy used for STEP sources
+  stepStreaming?: StepStreamingMode
+
+  // Whether STEP loading should also produce mesh evidence
+  mesh?: boolean
+
+  // Linear tolerance used while meshing exact BRep evidence
+  meshLinearTolerance?: number
+
+  // Angular tolerance in degrees used while meshing exact BRep evidence
+  meshAngularToleranceDegrees?: number
+
+  // Default work-unit budget for every claim on this subject
+  workUnitLimit?: number