geospec 0.1.0-beta.9 → 0.4.1-next.331

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

@@ -1,6 +1,6 @@
 # geospec — Types
 
-66 top-level symbols. Signatures are verbatim typescript.
+55 top-level symbols. Signatures are verbatim typescript.
 
 // A model admitted by one live GeoSpec host scope
 GeoSpecSubject: {
@@ -34,7 +34,7 @@ GeoSpecAssertion: {
      * holds for this millimetre box, never for the whole model.
      */
     region?: GeoSpecLoadRegion;
-    /** Wall-clock cost of matcher evaluation in milliseconds (R1: budgeted matchers only). */
+    /** Wall-clock cost of matcher evaluation in milliseconds (budgeted matchers only). */
     durationMs?: number;
 }
 
@@ -62,7 +62,7 @@ GeoSpecAssertion: {
   // The crop this assertion's subject was loaded with
   region?: GeoSpecLoadRegion
 
-  // Wall-clock cost of matcher evaluation in milliseconds (R1
+  // Wall-clock cost of matcher evaluation in milliseconds (budgeted matchers only)
   durationMs?: number
 
 // Assembly occurrence rule accepted by `expectGeo(...).toHaveAssemblyOccurrences(...)`
@@ -830,256 +830,6 @@ GeoSpecVolumeExpectation: {
 
   tolerance?: number
 
-// Basic exact or topology-derived BRep evidence consumed by early feature matchers
-BrepEvidence: {
-    validity?: {
-        valid: boolean;
-        checks?: Array<{
-            shape: string;
-            status: string;
-        }>;
-        maxTolerance?: number;
-        freeBounds?: {
-            count: number;
-        };
-        smallEdges?: Array<{
-            length: number;
-            shape?: string;
-            location?: Vec3;
-        }>;
-        sameParameter?: boolean;
-        closedShells?: boolean;
-        closedSolids?: boolean;
-        solidCount?: number;
-        invalidSolidCount?: number;
-        openEdgeCount?: number;
-        reason?: string;
-        closedWires?: boolean;
-    };
-    topologyCounts?: {
-        vertices?: number;
-        edges?: number;
-        wires?: number;
-        faces?: number;
-        shells?: number;
-        solids?: number;
-        compounds?: number;
-    };
-    boundingBox?: {
-        min: Vec3;
-        max: Vec3;
-        size: Vec3;
-        center: Vec3;
-    };
-    massProperties?: {
-        surfaceArea?: number;
-        volume?: number;
-        centerOfMass?: Vec3;
-        mass?: number;
-    };
-    planarFaces?: Array<{
-        normal: Vec3;
-        offset: number;
-        area?: number;
-        center?: Vec3;
-    }>;
-    cylindricalFaces?: Array<{
-        radius: number;
-        axis: 'x' | 'y' | 'z';
-        center?: Vec3;
-        axisRange?: {
-            min: number;
-            max: number;
-        };
-    }>;
-    circularHoles?: Array<{
-        diameter: number;
-        through: boolean;
-        axis: 'x' | 'y' | 'z';
-        center?: Vec3;
-        axisRange?: {
-            min: number;
-            max: number;
-        };
-    }>;
-    circularHolePatterns?: Array<{
-        count: number;
-        holeDiameter: number;
-        boltCircleDiameter: number;
-        axis: 'x' | 'y' | 'z';
-        center?: Vec3;
-    }>;
-    chamferFeatures?: Array<{
-        distance: number;
-        selection?: string;
-    }>;
-    filletFeatures?: Array<{
-        radius: number;
-        selection?: string;
-    }>;
-    minimumWallThickness?: {
-        value: number;
-        location?: Vec3;
-        pointA?: Vec3;
-        pointB?: Vec3;
-        solidIndex?: number;
-        tieCount?: number;
-        algorithm?: string;
-        tolerance?: number;
-        supportA?: {
-            faceIndex?: number;
-            surfaceType?: string;
-            supportType?: string;
-        };
-        supportB?: {
-            faceIndex?: number;
-            surfaceType?: string;
-            supportType?: string;
-        };
-        rejections?: Record<string, number>;
-    };
-}
-
-  validity?: {
-          valid: boolean;
-          checks?: Array<{
-              shape: string;
-              status: string;
-          }>;
-          maxTolerance?: number;
-          freeBounds?: {
-              count: number;
-          };
-          smallEdges?: Array<{
-              length: number;
-              shape?: string;
-              location?: Vec3;
-          }>;
-          sameParameter?: boolean;
-          closedShells?: boolean;
-          closedSolids?: boolean;
-          solidCount?: number;
-          invalidSolidCount?: number;
-          openEdgeCount?: number;
-          reason?: string;
-          closedWires?: boolean;
-      }
-
-  topologyCounts?: {
-          vertices?: number;
-          edges?: number;
-          wires?: number;
-          faces?: number;
-          shells?: number;
-          solids?: number;
-          compounds?: number;
-      }
-
-  boundingBox?: {
-          min: Vec3;
-          max: Vec3;
-          size: Vec3;
-          center: Vec3;
-      }
-
-  massProperties?: {
-          surfaceArea?: number;
-          volume?: number;
-          centerOfMass?: Vec3;
-          mass?: number;
-      }
-
-  planarFaces?: Array<{
-          normal: Vec3;
-          offset: number;
-          area?: number;
-          center?: Vec3;
-      }>
-
-  cylindricalFaces?: Array<{
-          radius: number;
-          axis: 'x' | 'y' | 'z';
-          center?: Vec3;
-          axisRange?: {
-              min: number;
-              max: number;
-          };
-      }>
-
-  circularHoles?: Array<{
-          diameter: number;
-          through: boolean;
-          axis: 'x' | 'y' | 'z';
-          center?: Vec3;
-          axisRange?: {
-              min: number;
-              max: number;
-          };
-      }>
-
-  circularHolePatterns?: Array<{
-          count: number;
-          holeDiameter: number;
-          boltCircleDiameter: number;
-          axis: 'x' | 'y' | 'z';
-          center?: Vec3;
-      }>
-
-  chamferFeatures?: Array<{
-          distance: number;
-          selection?: string;
-      }>
-
-  filletFeatures?: Array<{
-          radius: number;
-          selection?: string;
-      }>
-
-  minimumWallThickness?: {
-          value: number;
-          location?: Vec3;
-          pointA?: Vec3;
-          pointB?: Vec3;
-          solidIndex?: number;
-          tieCount?: number;
-          algorithm?: string;
-          tolerance?: number;
-          supportA?: {
-              faceIndex?: number;
-              surfaceType?: string;
-              supportType?: string;
-          };
-          supportB?: {
-              faceIndex?: number;
-              surfaceType?: string;
-              supportType?: string;
-          };
-          rejections?: Record<string, number>;
-      }
-
-// Geometry file formats understood by GeoSpec provenance
-GeometryFileFormat: MeshFileFormat | 'step' | 'stp'
-
-// Capability exposed by a loaded subject
-GeometryCapability: {
-    kind: 'mesh';
-    feature: 'triangles' | 'bounding-box' | 'connected-components' | 'watertightness' | 'surface-area' | 'volume' | 'center-of-mass' | 'distance' | 'component-overlap';
-} | {
-    kind: 'brep';
-    feature: 'validity' | 'topology-counts' | 'bounding-box' | 'mass-properties' | 'planar-faces' | 'cylindrical-faces' | 'circular-holes' | 'circular-hole-patterns' | 'chamfer-features' | 'fillet-features' | 'wall-thickness';
-} | {
-    kind: 'step';
-    feature: 'schema' | 'units' | 'product-structure' | 'reader-provenance';
-} | {
-    kind: 'unsupported';
-    feature: string;
-    reason: string;
-}
-
-  kind: 'mesh'
-
-  feature: 'triangles' | 'bounding-box' | 'connected-components' | 'watertightness' | 'surface-area' | 'volume' | 'center-of-mass' | 'distance' | 'component-overlap'
-
 // Diagnostic emitted by GeoSpec loaders, analyzers, and matchers
 GeometryDiagnostic: {
     code: KernelIssueCode | (string & {});
@@ -1110,233 +860,6 @@ GeometryDiagnostic: {
 
   details?: unknown
 
-// Provenance recorded by GeoSpec loaders
-GeometryProvenance: {
-    source: GeometrySource;
-    unit: GeoSpecUnit;
-    loader: 'gltf-transform' | 'in-memory' | 'opencascade-step';
-    contentHash?: string;
-    parameters?: Record<string, JSONValue>;
-    exportIntent?: GeometryExportIntent;
-}
-
-  source: GeometrySource
-
-  unit: GeoSpecUnit
-
-  loader: 'gltf-transform' | 'in-memory' | 'opencascade-step'
-
-  contentHash?: string
-
-  parameters?: Record<string, JSONValue>
-
-  exportIntent?: GeometryExportIntent
-
-// Source metadata for a loaded geometry subject
-GeometrySource: {
-    kind: 'bytes' | 'array-buffer' | 'blob' | 'file' | 'path' | 'url' | 'mesh-buffer' | 'readable-stream' | 'async-iterable';
-    format: GeometryFileFormat;
-    path?: string;
-    name?: string;
-    byteLength?: number;
-}
-
-  kind: 'bytes' | 'array-buffer' | 'blob' | 'file' | 'path' | 'url' | 'mesh-buffer' | 'readable-stream' | 'async-iterable'
-
-  format: GeometryFileFormat
-
-  path?: string
-
-  name?: string
-
-  byteLength?: number
-
-// Canonical P0 object under test for GeoSpec
-// Remarks: This is intentionally a GeoSpec-loaded subject rather than a Tau runtime contract. Runtime integrations pass GLB/glTF bytes or files into loaders.
-GeometrySubject: {
-    kind: 'geometry-subject';
-    /** Opaque engine-owned identifier used by every protocol claim. */
-    subjectId: string;
-    mesh: GeometrySubjectMeshEvidence;
-    brep?: BrepEvidence;
-    step?: StepEvidence;
-    provenance: GeometryProvenance;
-    capabilities: GeometryCapability[];
-    diagnostics: GeometryEvidenceDiagnostic[];
-}
-
-  kind: 'geometry-subject'
-
-  // Opaque engine-owned identifier used by every protocol claim
-  subjectId: string
-
-  mesh: GeometrySubjectMeshEvidence
-
-  brep?: BrepEvidence
-
-  step?: StepEvidence
-
-  provenance: GeometryProvenance
-
-  capabilities: GeometryCapability[]
-
-  diagnostics: GeometryEvidenceDiagnostic[]
-
-// Wire-safe mesh summary carried by an opaque geometry subject
-GeometrySubjectMeshEvidence: {
-    format: MeshFileFormat;
-    stats: Pick<GeometryStats, 'vertexCount' | 'meshCount' | 'triangleCount'>;
-}
-
-  format: MeshFileFormat
-
-  stats: Pick<GeometryStats, 'vertexCount' | 'meshCount' | 'triangleCount'>
-
-// Mesh evidence loaded from geometry bytes or buffers
-MeshEvidence: {
-    format: MeshFileFormat;
-    stats: GeometryStats;
-}
-
-  format: MeshFileFormat
-
-  stats: GeometryStats
-
-// Geometry file formats supported by the P0 mesh loader
-MeshFileFormat: 'glb' | 'gltf' | 'mesh-buffer'
-
-// Triangle quality and scalar mesh metrics used by P0 GeoSpec matchers
-// Remarks: Values are reported in the glTF document coordinate units.
-MeshQualityStats: {
-    triangleCount: number;
-    nonFiniteVertices: Array<{
-        primitive: string;
-        vertexIndex: number;
-        position: [number, number, number];
-    }>;
-    degenerateTriangles: Array<{
-        primitive: string;
-        triangleIndex: number;
-        area: number;
-        center: [number, number, number];
-    }>;
-    duplicateFaces: Array<{
-        primitive: string;
-        triangleIndex: number;
-        firstTriangleIndex: number;
-    }>;
-    triangles: MeshTriangle[];
-    surfaceArea: number;
-    signedVolume: number;
-    centerOfMass?: Vec3;
-}
-
-  triangleCount: number
-
-  nonFiniteVertices: Array<{
-          primitive: string;
-          vertexIndex: number;
-          position: [number, number, number];
-      }>
-
-  degenerateTriangles: Array<{
-          primitive: string;
-          triangleIndex: number;
-          area: number;
-          center: [number, number, number];
-      }>
-
-  duplicateFaces: Array<{
-          primitive: string;
-          triangleIndex: number;
-          firstTriangleIndex: number;
-      }>
-
-  triangles: MeshTriangle[]
-
-  surfaceArea: number
-
-  signedVolume: number
-
-  centerOfMass?: Vec3
-
-// One triangle from mesh evidence, in geometry document coordinates
-MeshTriangle: {
-    primitive: string;
-    triangleIndex: number;
-    a: [number, number, number];
-    b: [number, number, number];
-    c: [number, number, number];
-    center: [number, number, number];
-    area: number;
-}
-
-  primitive: string
-
-  triangleIndex: number
-
-  a: [number, number, number]
-
-  b: [number, number, number]
-
-  c: [number, number, number]
-
-  center: [number, number, number]
-
-  area: number
-
-// STEP/XDE evidence extracted while loading a STEP subject
-StepEvidence: {
-    schema?: string;
-    unit?: GeoSpecUnit;
-    productStructure?: Array<{
-        name: string;
-        path: string;
-        transform?: number[];
-    }>;
-    readStrategy: {
-        strategy: 'native-stream' | 'filesystem';
-        inputKind: GeometrySource['kind'];
-        bytesRead: number;
-        nativeReadStream: boolean;
-        copiedToEmscriptenFs: boolean;
-    };
-    capabilities: Array<{
-        feature: string;
-        supported: boolean;
-        reason?: string;
-    }>;
-    /** Structured AP242 XDE read result (occurrences, subshape names, datum placements). */
-    xde?: XdeReadResult;
-}
-
-  schema?: string
-
-  unit?: GeoSpecUnit
-
-  productStructure?: Array<{
-          name: string;
-          path: string;
-          transform?: number[];
-      }>
-
-  readStrategy: {
-          strategy: 'native-stream' | 'filesystem';
-          inputKind: GeometrySource['kind'];
-          bytesRead: number;
-          nativeReadStream: boolean;
-          copiedToEmscriptenFs: boolean;
-      }
-
-  capabilities: Array<{
-          feature: string;
-          supported: boolean;
-          reason?: string;
-      }>
-
-  // Structured AP242 XDE read result (occurrences, subshape names, datum placements)
-  xde?: XdeReadResult
-
 // Numeric 3D vector
 Vec3: readonly [number, number, number]
 
@@ -1752,3 +1275,85 @@ 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
 
-46 top-level symbols. Signatures are verbatim typescript.
+48 top-level symbols. Signatures are verbatim typescript.
 
 // GeoSpec suite helper used inside VM-executed test modules
 // describe (function)
@@ -129,6 +129,11 @@ export declare function runGeoSpecModule(options: RunGeoSpecModuleOptions): Prom
 export declare function isGeoSpecTimeoutCode(code: string): code is GeoSpecTimeoutCode;
 //   code: Any diagnostic or issue code
 
+// Create GeoSpec's default module VM
+// createPlainModuleVm (function)
+export declare function createPlainModuleVm(options: ModuleVmOptions): Promise<ModuleVm>;
+//   options: The project filesystem
+
 // Compose compiled assertion and model bindings with the SDK's serial lifecycle
 // createNativeGeoSpecRunner (function)
 export declare function createNativeGeoSpecRunner(options: GeoSpecNativeRunnerOptions): GeoSpecRunner;
@@ -244,6 +249,21 @@ export declare function installGeoSpecVitest(client: GeoSpecAssertionClient): Ge
 export declare function setupGeoSpecVitest(options: GeoSpecAssertionClientOptions): GeoSpecVitestAdapter;
 //   options: Flat native assertion-client options
 
+// Configure GeoSpec for the active Vitest file from the project's `geospec.config.*`, the file the `geospec` CLI reads
+// Remarks: Call it at the top level of a test file or a setup file and await it. Subjects are released, and an engine this call created is closed, after the file's tests.
+// setupGeoSpecVitestProject (function)
+export declare function setupGeoSpecVitestProject(options: SetupGeoSpecVitestProjectOptions): Promise<GeoSpecVitestProject>;
+//   options: Project root, config file, overrides and assertion-client options
+// Example (A Vitest file over a project with a geospec.config.ts):
+//   import { expect, it } from 'vitest';
+//   import { setupGeoSpecVitestProject } from 'geospec/vitest/node';
+//   
+//   const geo = await setupGeoSpecVitestProject({ projectPath: import.meta.dirname });
+//   
+//   it('has the intended volume', async () => {
+//   await expect(await geo.loadModel({ file: 'part.step' })).toHaveVolume({ value: 1000, tolerance: 1 });
+//   });
+
 // 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)