geospec 0.1.0-beta.8 → 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

@@ -490,6 +490,7 @@ To read any other signature, find its name in `api-index.md`, which lists all 36
 - `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-index.md

@@ -1,6 +1,6 @@
 # geospec API index
 
-geospec 0.1.0-beta.8 · 368 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.
 
@@ -363,7 +363,10 @@ LoadModelOptions (type) [lines 1729-1754] [8 members] — Options accepted by {@
   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 1756-1836] [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

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

@@ -1,6 +1,6 @@
 # geospec — Types
 
-67 top-level symbols. Signatures are verbatim typescript.
+66 top-level symbols. Signatures are verbatim typescript.
 
 // A model admitted by one live GeoSpec host scope
 GeoSpecSubject: {
@@ -648,7 +648,7 @@ GeoSpecProductStructureExpectation: {
   count?: GeoSpecNumericExpectation
 
 // One spatial relationship accepted by `expectGeo(...).toHaveSpatialRelationships(...)`
-// Remarks: Verdicts are decided by exact BRep evidence only (D3): extrema for `contact`/`clearance`, analytic fact comparison for `coaxial`/`concentric`/`coplanar`/`parallel`/`perpendicular`/`angle`, exact solid classification for `containment`/`insertion`, and exact boolean common volume for `interference` (positive volume outside the `minVolume`/`maxVolume` allowance band fails).
+// Remarks: Each kind admits narrow geometry and refuses outside it, never falling back to an estimate (D3). On STEP, `clearance`, `contact`, `insertion` and `interference` take complete box-shaped occurrences (`insertion` also a Cartesian `axis`); `coaxial`, `concentric`, `coplanar`, `parallel`, `perpendicular` and `angle` take one analytic face, axis or plane per endpoint; `containment` takes closed solids. On glTF/GLB, `body` endpoints admit `contact`, `clearance`, `containment` and `interference` over closed shells. Shared volume for `interference` must lie in `[minVolume, maxVolume]`.
 GeoSpecSpatialRelationshipExpectation: {
     id?: string;
     kind: 'contact' | 'clearance' | 'coaxial' | 'concentric' | 'coplanar' | 'parallel' | 'perpendicular' | 'angle' | 'containment' | 'insertion' | 'interference';
@@ -1752,85 +1752,3 @@ LoadModelOptions: LoadModelSourceOptions | LoadModelCodeOptions<Code> | LoadMode
 
   // Default work-unit budget for every claim on this subject
   workUnitLimit?: number
-
-// 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

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

@@ -1,6 +1,6 @@
 # geospec — Functions
 
-39 top-level symbols. Signatures are verbatim typescript.
+46 top-level symbols. Signatures are verbatim typescript.
 
 // GeoSpec suite helper used inside VM-executed test modules
 // describe (function)
@@ -160,6 +160,24 @@ export declare function resolveUnderRoot(root: string, path: string): string;
 //   root: The project root
 //   path: A canonical path rooted by the supplied project capability
 
+// Create a GeoSpec engine for this process
+// Throws: Error when the native addon is installed but cannot load, or the permits are invalid.
+// createNodeGeoSpecEngine (function)
+export declare function createNodeGeoSpecEngine(options?: CreateNodeGeoSpecEngineOptions): Promise<NodeGeoSpecEngine>;
+//   options: CPU permits for the native addon
+
+// Create a pool with one engine and one set of exporters constructed inside each worker
+// Remarks: Workers are threads of this process and share one OCCT library instance and pool width, so inner parallelism is all-or-nothing: either several workers with one permit each, or one worker holding the whole budget. A budget above the worker count with more than one worker is refused before any worker starts rather than silently run serial.
+// Throws: RangeError When the budget is invalid, exceeds the host cap, or gives any of several in-process workers more than one permit.
+// createGeoSpecNodePoolRunner (function)
+export declare function createGeoSpecNodePoolRunner(options: GeoSpecNodePoolOptions): GeoSpecRunner;
+//   options: Project, config, exporter modules, outer workers and caller-inclusive CPU budget
+
+// Adapt a Node worker thread to the pool's host-agnostic handle
+// createNodeWorkerHandle (function)
+export declare function createNodeWorkerHandle(worker: NodeWorkerLike): GeoSpecPoolWorkerHandle;
+//   worker: The spawned worker
+
 // Create a run-level issue when filters select no tests
 // createNoMatchingGeoSpecTestsIssue (function)
 export declare function createNoMatchingGeoSpecTestsIssue(): VmIssue;
@@ -189,7 +207,7 @@ export declare function createGeoSpecMatcherMethods<Result>(options: {
 //   options: Subject, polarity and host invocation function
 
 // Submit an ancillary query with positive polarity through the native core
-// Remarks: Queries return full reports even when failed or refused. Protocol errors propagate unchanged. Rust owns defaults, validation and canonical encoding.
+// Remarks: A query asserts nothing, so it never fails: when the evidence it reads is missing or cannot decide it returns a full refused report whose diagnostic names the reason, such as `GEOSPEC_UNSUPPORTED_EVIDENCE`. Protocol errors propagate unchanged. Rust owns defaults, validation and canonical encoding.
 // evaluateGeoSpecNativeQuery (function)
 export declare function evaluateGeoSpecNativeQuery(options: GeoSpecNativeQueryOptions): GeoSpecCanonicalClaimReport;
 //   options: Query identity, subject and authored payload
@@ -200,6 +218,17 @@ export declare function evaluateGeoSpecNativeQuery(options: GeoSpecNativeQueryOp
 export declare function resolveGeoSpecMaximumWorkUnitLimit(maximum?: number): number;
 //   maximum: The host's configured maximum, when it sets one
 
+// Run the CLI
+// runGeoSpecCli (function)
+export declare function runGeoSpecCli(argv: readonly string[], host: GeoSpecCliHost): Promise<number>;
+//   argv: Arguments after the executable and script
+//   host: The injected platform
+
+// Build the Node CLI host
+// createNodeGeoSpecCliHost (function)
+export declare function createNodeGeoSpecCliHost(options?: NodeGeoSpecCliHostOptions): GeoSpecCliHost;
+//   options: Report sink and host-supplied exporter modules
+
 // Create Vitest matchers over an existing runner-independent client
 // createGeoSpecVitestAdapter (function)
 export declare function createGeoSpecVitestAdapter(client: GeoSpecAssertionClient): GeoSpecVitestAdapter;
@@ -215,8 +244,20 @@ export declare function installGeoSpecVitest(client: GeoSpecAssertionClient): Ge
 export declare function setupGeoSpecVitest(options: GeoSpecAssertionClientOptions): GeoSpecVitestAdapter;
 //   options: Flat native assertion-client options
 
+// Type a `geospec.config.*` default export
+// Remarks: An identity at runtime. The parameter is not generic, so an object literal gets the excess-property and contextual checks `satisfies GeoSpecConfig` gives, in `.ts` and `.js` alike.
+// defineConfig (function)
+export declare function defineConfig(config: GeoSpecConfig): GeoSpecConfig;
+//   config: The project configuration
+
+// Read a project's `geospec.config.*` data fields through the spec VM, the same way on every host
+// Remarks: Discovery is `loadGeoSpecConfig`'s: exactly one of `geospec.config.{ts,mts,js,mjs}`. The config may import `geospec/config` (for `defineConfig`) and project files, nothing from `node_modules`: imports are detected first, without a network call, so a config with exporters is `not-applied` rather than fetched. `exporters` are never returned; a host that reads the config holds its own.
+// readGeoSpecConfig (function)
+export declare function readGeoSpecConfig(options: ReadGeoSpecConfigOptions): Promise<ReadGeoSpecConfigResult>;
+//   options: The project filesystem and the rooted project directory
+
 // Load one trusted project config using Node's native module loader
-// 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.
+// Remarks: Explicit selection or exactly one geospec.config.js/.mjs/.ts/.mts is allowed. A config's `geospec/config` import resolves to this copy when the project has no install of its own. 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.
 // loadGeoSpecConfig (function)
 export declare function loadGeoSpecConfig(options: LoadGeoSpecConfigOptions): Promise<LoadedGeoSpecConfig>;
 //   options: Project, optional explicit config and defined option overrides