geospec 0.1.0-beta.8 → 0.1.0-beta.9

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (56) hide show
  1. package/README.md +41 -8
  2. package/agent/geospec-authoring/SKILL.md +1 -0
  3. package/agent/geospec-authoring/api-index.md +5 -2
  4. package/agent/geospec-authoring/api-types-2.md +85 -0
  5. package/agent/geospec-authoring/api-types.md +2 -84
  6. package/agent/geospec-authoring/public-api-functions.md +44 -3
  7. package/agent/geospec-authoring/public-api-index.md +136 -97
  8. package/agent/geospec-authoring/public-api-types-2.md +108 -182
  9. package/agent/geospec-authoring/public-api-types-3.md +308 -28
  10. package/agent/geospec-authoring/public-api-types.md +1 -1
  11. package/agent/resources.js +12 -11
  12. package/agent/skills.json +3 -2
  13. package/dist/assertion-client/client.d.mts +3 -1
  14. package/dist/cli/cli.d.mts +48 -0
  15. package/dist/cli/cli.mjs +30 -0
  16. package/dist/cli/index.d.mts +3 -0
  17. package/dist/cli/index.mjs +1 -0
  18. package/dist/cli/main.d.mts +1 -0
  19. package/dist/cli/main.mjs +2 -0
  20. package/dist/cli/node-host.d.mts +26 -0
  21. package/dist/cli/node-host.mjs +1 -0
  22. package/dist/cli/wire-value.mjs +1 -0
  23. package/dist/config/define-config.d.mts +15 -0
  24. package/dist/config/define-config.mjs +2 -0
  25. package/dist/config/index.d.mts +4 -2
  26. package/dist/config/index.mjs +1 -1
  27. package/dist/config/node/load.d.mts +2 -1
  28. package/dist/config/node/load.mjs +1 -1
  29. package/dist/config/read-geospec-config.d.mts +47 -0
  30. package/dist/config/read-geospec-config.mjs +3 -0
  31. package/dist/config/types.d.mts +11 -22
  32. package/dist/config/validate.mjs +1 -1
  33. package/dist/engine/client.d.mts +3 -1
  34. package/dist/model/node/command-exporter.d.mts +2 -0
  35. package/dist/model/node/command-exporter.mjs +1 -1
  36. package/dist/runner/index.d.mts +1 -1
  37. package/dist/runner/native/index.mjs +1 -1
  38. package/dist/runner/native/native-serial-runner.mjs +1 -1
  39. package/dist/runner/node/engine.d.mts +40 -0
  40. package/dist/runner/node/engine.mjs +1 -0
  41. package/dist/runner/node/index.d.mts +4 -1
  42. package/dist/runner/node/index.mjs +1 -1
  43. package/dist/runner/node/node-vm-filesystem.mjs +1 -1
  44. package/dist/runner/node/pool-runner.d.mts +67 -0
  45. package/dist/runner/node/pool-runner.mjs +1 -0
  46. package/dist/runner/node/pool-worker-entry.d.mts +43 -0
  47. package/dist/runner/node/pool-worker-entry.mjs +1 -0
  48. package/dist/runner/pool/pool-messages.d.mts +2 -0
  49. package/dist/runner/pool/pool.d.mts +1 -1
  50. package/dist/runner/pool/pool.mjs +1 -1
  51. package/dist/runner/pool/worker-host.d.mts +1 -1
  52. package/dist/runner/run-geospec-module.mjs +7 -7
  53. package/dist/runner/types.d.mts +9 -6
  54. package/dist/runner/worker/index.d.mts +1 -1
  55. package/dist/runner/worker/serial-runner.mjs +1 -1
  56. package/package.json +18 -5
@@ -648,7 +648,7 @@ GeoSpecProductStructureExpectation: {
648
648
  count?: GeoSpecNumericExpectation
649
649
 
650
650
  // One spatial relationship accepted by `expectGeo(...).toHaveSpatialRelationships(...)`
651
- // 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).
651
+ // 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]`.
652
652
  GeoSpecSpatialRelationshipExpectation: {
653
653
  id?: string;
654
654
  kind: 'contact' | 'clearance' | 'coaxial' | 'concentric' | 'coplanar' | 'parallel' | 'perpendicular' | 'angle' | 'containment' | 'insertion' | 'interference';
@@ -4,23 +4,24 @@ export default Object.freeze([
4
4
  slug: "geospec-authoring",
5
5
  name: "GeoSpec authoring",
6
6
  description: "Guides canonical GeoSpec geometry tests in TypeScript or JavaScript for every Tau kernel. Use for *.geospec.ts and *.geospec.js tests.",
7
- version: "0.1.0-beta.8",
7
+ version: "0.1.0-beta.9",
8
8
  whenToUse: "Use before creating or editing *.geospec.ts or *.geospec.js tests, for a model in any kernel.",
9
- body: "---\nname: geospec-authoring\ndescription: Guides canonical GeoSpec geometry tests in TypeScript or JavaScript for every Tau kernel. Use for *.geospec.ts and *.geospec.js tests.\n---\n\n# GeoSpec authoring\n\nWrite tests before implementation; assert deterministic, measurable properties.\n\n## Test shape\n\n- Use `*.geospec.ts` or `*.geospec.js`. Import `describe`, `it` and `expectGeo` from `geospec`, and `loadModel` from `geospec/model`.\n- Await `loadModel`, then assert synchronously with `expectGeo(model)`. The host supplies the compiled binding; authoring does not select an engine.\n- Await or return the complete model-load chain from the test callback; detached future loads are not part of a completed test.\n- Omit `parameters` for model-code defaults; use `{ file, parameters }` for variants. Loaded subjects are opaque.\n- `loadModel({ file })` resolves `file` against the project root, the same root as every tool's `targetFile`; the result names that root as `projectRoot` where the host reports it, as `tau mcp` does. A suite in a subfolder names the model by its path from that root, or passes `rootDir`, the project-relative folder the model is in: `loadModel({ file: 'main.ts', rootDir: 'parts/gear' })` loads `parts/gear/main.ts`. A file the root does not hold refuses with `GEOSPEC_MODEL_SOURCE_NOT_FOUND`, which names the root and the path it looked for.\n\nCanonical TypeScript authoring:\n\n```ts\nimport { describe, expectGeo, it } from 'geospec';\nimport { loadModel } from 'geospec/model';\n\ndescribe('main geometry', () => {\n it('has the intended envelope', async () => {\n const model = await loadModel({ file: 'main.ts', parameters: { width: 120 } });\n expectGeo(model).toHaveBoundingBox({ size: { x: 120 }, tolerance: 1 });\n });\n});\n```\n\nSpecs are always TypeScript or JavaScript, whatever the model's kernel: `loadModel({ file })` evaluates `main.ts`, `main.tsx`, `main.py`, `main.scad`, `main.kcl` or `main.cs` through Tau's runtime. `test_model` discovers `*.geospec.ts` and `*.geospec.js` only.\n\nEvery matcher takes one expectation object:\n\n- Wrong: `expectGeo(model).toHaveVolume(5000, { tolerance: 5 })`. Correct: `expectGeo(model).toHaveVolume({ value: 5000, tolerance: 5 })`.\n- Wrong: `await expectGeo(model)…`. Correct: await `loadModel`, then assert synchronously.\n- Wrong: exact-feature matchers on a mesh kernel (Manifold, JSCAD, OpenSCAD, PicoGK, PicoVoxel). Correct: `toBeValidBrep`, `toHaveTopologyCounts`, the face, hole, pattern, chamfer, fillet and wall-thickness matchers, `toHaveStepUnits`, `toHaveProductStructure` and `toHaveVoidContinuity` need STEP BRep evidence and report unsupported on meshes; assert meshes with bounds, volume, surface area, connected components and `toBeWatertight`.\n\n## Loads and budgets\n\n- GeoSpec has no `beforeAll`. Write each `loadModel` inside its own `it`: within one run, identical loads (same file or code, parameters, format, tolerances and region) share one export and one admission. Each load keeps its own `loadId` and records `reused: true`, and a file is reused only while its source closure is unchanged.\n- `loadModel({ file, workUnitLimit })` sets the default claim budget for that subject, and `expectGeo(model, { workUnitLimit })` overrides it for one chain. The budget is a positive integer no greater than 512000000. A `MATCHER_TIMEOUT` refusal reports `details.limit` and, when measured, `details.used`; its `test_model` row (category `work-budget`) names in `limit.retry` the one `workUnitLimit` that can decide the claim, or `null` at the host maximum. Never treat the refusal as a pass.\n- `loadModel({ file, region: { min: [x, y, z], max: [x, y, z] } })` makes a separate claim about one millimetre box, never a stand-in for a whole-model claim. The kernel crops before export (PicoVoxel trims Voxels parts), and other kernels, STEP loads and unconfirmed crops refuse with a typed diagnostic. A cropped subject answers only bounding box, volume, surface area, mass and center of mass of its region, and its assertions record the region. Every other matcher on it refuses with `GEOSPEC_REGION_WHOLE_MODEL_CLAIM`. Name the region in the test, and keep whole-model claims on whole-model loads.\n- A host or engine limit leaves a claim undecided, never false: `test_model` reports it as inconclusive with category `analysis-limit`, `resource-limit` or `work-budget` and a typed `limit` naming the limit and its numbers. Keep the model as designed: never coarsen, shrink or crop it to fit. Only a `work-budget` row's `limit.retry` is a retry, and `testTimeout` only answers a `timeout` row; report every other limit row as not decided at this capacity.\n- `toHaveCenterOfMass({ point, tolerance })` takes an exact point. Per-axis ranges such as `{ y: { greaterThan: 1 } }` are refused.\n\n## Ceilings\n\nFixed in this release; design within them, and report a claim that meets one as not decided.\n\n| Ceiling | Value | Where an agent meets it |\n| ------------------------------------- | -------------------- | --------------------------------------------------------------------------------------------------------------------------------- |\n| `maxSubjectBytes`, `maxResourceBytes` | 64 MiB each | A mesh `loadModel({ file })` exports about 72 bytes per triangle, so admission refuses near 930,000 triangles (`resource-limit`). |\n| `maxTotalBinaryBytes` | 128 MiB | All subjects of one load together. |\n| `maxTriangles`, `maxVertices` | 4,000,000, 2,000,000 | A decoded mesh. |\n| `continuousEvidenceBytes` | 32 MiB | `toHaveNoComponentInterference` on a large assembly (`analysis-limit`). |\n| `workUnitLimit` | 512000000 at most | Any claim; the only limit an argument raises. |\n\nLoad `format: 'step'` only for the exact-BRep matchers above; every other matcher answers on the cheaper mesh.\n\n## Coverage\n\nBounds and physical properties are insufficient. Cover major components, named features, variants, dimensions/positions, disjoint counts, closure, interference and supported exact features. Explicitly report unsupported requirements; proxies cannot fulfill them.\n\n- `toHaveBoundingBox`: size/position.\n- `toHaveConnectedComponents`: qualified material connectivity; visual touching cannot justify tolerance changes.\n- `toBeWatertight`: closed edge incidence, not manifold validity, fusion or material connectivity. Bounds prove none of these. Missing evidence is unsupported.\n- `toHaveSurfaceArea`, `toHaveVolume`, `toHaveCenterOfMass`, `toHaveMass`: physical measurements.\n- `toHaveNoComponentInterference`: overlap; allow deliberate press fits.\n- `loadModel({ file, format: 'step' })`: use BRep evidence for supported topology and feature assertions. Missing occurrence, interference, clearance, containment, lumen, wall, section or motion evidence is unsupported, not a pass or an envelope substitute.\n\nTest assemblies and independent units; preserve sibling coverage when adding files. Non-top-level geometry needs kernel export/invocation, not test removal.\n\nFix geometry at its root; never weaken tolerances, delete assertions, or reduce detail to pass.\n\n`public-api-index.md` covers the host and framework API; authoring needs only the Core API below and `api-*` files.\n\n## Core API\n\nThe symbols real Tau models use most, as verbatim declarations. Anything not shown is in the API reference below.\n\n### Functions\n\n```ts\n// Start a geometry assertion chain\nexport declare function expectGeo(subject: GeoSpecSubject, options?: GeoSpecExpectOptions): GeoSpecMatcher;\n\n// A model admitted by one live GeoSpec host scope\nGeoSpecSubject: {\n readonly [subjectBrand]: true\n}\n\n// Per-chain options accepted by `expectGeo(subject, options)`\nGeoSpecExpectOptions: {\n // Deterministic work-unit budget for every claim in this chain\n readonly workUnitLimit?: number\n}\n\n// Load a CAD model into GeoSpec evidence\nexport declare function loadModel<Code extends Record<string, string> = Record<string, string>>(_options: LoadModelOptions<Code>): Promise<GeoSpecSubject>;\n\n// Options accepted by {@link import ('./load-model.js').loadModel}\nLoadModelOptions: LoadModelSourceOptions | LoadModelCodeOptions<Code> | LoadModelFileOptions\n // Project-relative folder `file` resolves in, for a suite that loads from somewhere other than…\n rootDir?: string\n // Geometry format to export\n format?: GeoSpecModelFormat\n // Explicit parameters passed to the exporter\n parameters?: Record<string, unknown>\n // STEP reader strategy used for STEP exports\n stepStreaming?: StepStreamingMode\n // Whether STEP loading should also produce mesh evidence\n mesh?: boolean\n // Linear tolerance used while meshing exact BRep evidence\n meshLinearTolerance?: number\n // Angular tolerance in degrees used while meshing exact BRep evidence\n meshAngularToleranceDegrees?: number\n // Default work-unit budget for every claim on this subject\n workUnitLimit?: number\n\n// Geometry formats accepted by {@link import ('./load-model.js').loadModel}\nGeoSpecModelFormat: MeshFileFormat | 'step' | 'stp'\n\n// GeoSpec test helper used inside VM-executed test modules\nexport declare function it(name: string, function_: GeoSpecTestCallback): void;\n skip(name: string, function_?: GeoSpecTestCallback): void;\n\n// GeoSpec suite helper used inside VM-executed test modules\nexport declare function describe(name: string, function_: GeoSpecTestCallback): void;\n skip(name: string, function_?: GeoSpecTestCallback): void;\n\n// Alias for {@link it}\nexport declare function test(name: string, function_: GeoSpecTestCallback): void;\n skip(name: string, function_?: GeoSpecTestCallback): void;\n```\n\n### Types\n\n```ts\n// Assertion chain returned by `expectGeo(subject)`\nGeoSpecMatcher: {\n // Core-owned negation\n readonly not: Omit<GeoSpecMatcher, 'not'>\n // Assert the fixed rational plate contract\n toSatisfyRationalPlate(): GeoSpecAssertion;\n // Assert the fixed parallel-plane distance contract\n toSatisfyParallelPlaneDistance(): GeoSpecAssertion;\n // Assert axis-aligned bounds, size, or center for a loaded geometry subject\n toHaveBoundingBox(first: Vec3 | GeoSpecBoundingBoxExpectation, second?: Vec3): GeoSpecAssertion;\n // Assert how many spatially disjoint chunks the mesh contains\n toHaveConnectedComponents(expected: GeoSpecConnectedComponentsExpectation): GeoSpecAssertion;\n // Assert closed mesh edge incidence\n toBeWatertight(): GeoSpecAssertion;\n // Assert that separate assembly components do not occupy the same solid volume\n toHaveNoComponentInterference(expected?: GeoSpecComponentInterferenceExpectation): GeoSpecAssertion;\n // Assert that named assembly occurrences exist with expected counts and bounds\n toHaveAssemblyOccurrences(expected: GeoSpecAssemblyOccurrencesExpectation): GeoSpecAssertion;\n // Assert that selected entities satisfy declared spatial relationships\n toHaveSpatialRelationships(expected: GeoSpecSpatialRelationshipsExpectation): GeoSpecAssertion;\n // Assert rendered mesh evidence is internally trustworthy for downstream checks\n toHaveMeshIntegrity(expected: GeoSpecMeshIntegrityExpectation): GeoSpecAssertion;\n // Assert that the subject carries no diagnostics at the rejected severities\n toHaveNoDiagnostics(expected?: GeoSpecNoDiagnosticsExpectation): GeoSpecAssertion;\n // Assert total surface area, preferring exact BRep mass properties when available\n toHaveSurfaceArea(expected: GeoSpecSurfaceAreaExpectation): GeoSpecAssertion;\n // Assert enclosed volume, preferring exact BRep mass properties when available\n toHaveVolume(expected: GeoSpecVolumeExpectation): GeoSpecAssertion;\n // Assert mass derived from exact mass properties or volume times density\n toHaveMass(expected: GeoSpecMassExpectation): GeoSpecAssertion;\n // Assert the center of mass or mesh-derived centroid for a closed subject\n toHaveCenterOfMass(expected: GeoSpecCenterOfMassExpectation): GeoSpecAssertion;\n // Assert that exact BRep evidence reports a valid shape\n toBeValidBrep(expected?: GeoSpecValidBrepExpectation): GeoSpecAssertion;\n // Assert exact BRep topology counts\n toHaveTopologyCounts(expected: GeoSpecTopologyCountsExpectation): GeoSpecAssertion;\n // Assert the STEP unit evidence\n toHaveStepUnits(expected: GeoSpecStepUnitsExpectation): GeoSpecAssertion;\n // Assert STEP product-structure evidence\n toHaveProductStructure(expected: GeoSpecProductStructureExpectation): GeoSpecAssertion;\n // Assert that BRep evidence contains a planar face matching the requested constraints\n toHavePlanarFace(expected: GeoSpecPlanarFaceExpectation): GeoSpecAssertion;\n // Assert that BRep evidence contains a cylindrical face with the requested radius and axis\n toHaveCylindricalFace(expected: GeoSpecCylindricalFaceExpectation): GeoSpecAssertion;\n // Assert that BRep evidence contains a circular hole matching diameter, center, and axis\n toHaveCircularHole(expected: GeoSpecCircularHoleExpectation): GeoSpecAssertion;\n // Assert that BRep evidence contains a repeated circular-hole pattern\n toHaveCircularHolePattern(expected: GeoSpecCircularHolePatternExpectation): GeoSpecAssertion;\n // Assert that BRep evidence contains a chamfer feature with the requested distance\n toHaveChamferFeature(expected: GeoSpecChamferFeatureExpectation): GeoSpecAssertion;\n // Assert that BRep evidence contains a fillet feature with the requested radius\n toHaveFilletFeature(expected: GeoSpecFilletFeatureExpectation): GeoSpecAssertion;\n // Assert that BRep evidence reports a minimum wall thickness satisfying the expectation\n toHaveMinimumWallThickness(expected: GeoSpecMinimumWallThicknessExpectation): GeoSpecAssertion;\n // Assert that the declared waypoints share one connected void, stay isolated from the declared…\n toHaveVoidContinuity(expected: GeoSpecVoidContinuityExpectation): GeoSpecAssertion;\n}\n\n// Numeric 3D vector\nVec3: readonly [number, number, number]\n\n// Bounding-box expectation accepted by `expectGeo(...).toHaveBoundingBox(...)`\nGeoSpecBoundingBoxExpectation: {\n min?: Vec3 | Partial<Record<keyof GeoSpecAxisExpectation, GeoSpecNumericExpectation>>\n max?: Vec3 | Partial<Record<keyof GeoSpecAxisExpectation, GeoSpecNumericExpectation>>\n size?: Vec3 | Partial<Record<keyof GeoSpecAxisExpectation, GeoSpecNumericExpectation>>\n center?: Vec3 | Partial<Record<keyof GeoSpecAxisExpectation, GeoSpecNumericExpectation>>\n tolerance?: number\n}\n\n// Connected-components expectation accepted by `expectGeo(...).toHaveConnectedComponents(...)`\nGeoSpecConnectedComponentsExpectation: {\n count: number\n tolerance?: number\n toleranceMm?: number\n}\n\n// Component-interference expectation accepted by `expectGeo(...).toHaveNoComponentInterference(...)`\nGeoSpecComponentInterferenceExpectation: {\n tolerance?: number\n pairs?: GeoSpecComponentInterferencePairExpectation[]\n allowances?: GeoSpecComponentInterferenceAllowance[]\n}\n\n// Assembly occurrence expectation accepted by `expectGeo(...).toHaveAssemblyOccurrences(...)`\nGeoSpecAssemblyOccurrencesExpectation: {\n occurrences: GeoSpecAssemblyOccurrenceExpectation[]\n uniqueNames?: boolean\n}\n\n// Spatial relationship expectation accepted by `expectGeo(...).toHaveSpatialRelationships(...)`\nGeoSpecSpatialRelationshipsExpectation: {\n relationships: GeoSpecSpatialRelationshipExpectation[]\n}\n\n// Mesh integrity expectation accepted by `expectGeo(...).toHaveMeshIntegrity(...)`\nGeoSpecMeshIntegrityExpectation: {\n finitePositions?: boolean\n degenerateTriangles?: {\n count?: number;\n maxCount?: number;\n areaTolerance?: number;\n }\n duplicateFaces?: {\n count?: number;\n maxCount?: number;\n }\n watertight?: boolean\n triangleCount?: GeoSpecNumericExpectation\n}\n\n// Diagnostic severities rejected by `expectGeo(...).toHaveNoDiagnostics(...)`\nGeoSpecNoDiagnosticsExpectation: {\n severities?: Array<GeometryDiagnostic['severity']>\n}\n\n// Surface-area expectation accepted by `expectGeo(...).toHaveSurfaceArea(...)`\nGeoSpecSurfaceAreaExpectation: {\n value: number | GeoSpecNumericExpectation\n tolerance?: number\n}\n\n// Volume expectation accepted by `expectGeo(...).toHaveVolume(...)`\nGeoSpecVolumeExpectation: {\n value: number | GeoSpecNumericExpectation\n tolerance?: number\n}\n\n// Mass expectation accepted by `expectGeo(...).toHaveMass(...)`\nGeoSpecMassExpectation: {\n value: number | GeoSpecNumericExpectation\n density?: number\n tolerance?: number\n}\n\n// Center-of-mass expectation accepted by `expectGeo(...).toHaveCenterOfMass(...)`\nGeoSpecCenterOfMassExpectation: {\n // Exact expected point in millimetres\n point: GeoSpecPointExpectation\n tolerance?: number\n}\n\n// Exact BRep validity expectation accepted by `expectGeo(...).toBeValidBrep(...)`\nGeoSpecValidBrepExpectation: {\n maxTolerance?: number\n freeBounds?: {\n count?: GeoSpecNumericExpectation;\n }\n minEdgeLength?: number\n sameParameter?: boolean\n closedShells?: boolean\n closedWires?: boolean\n}\n\n// Topology-count expectation accepted by `expectGeo(...).toHaveTopologyCounts(...)`\nGeoSpecTopologyCountsExpectation: {\n vertices?: GeoSpecNumericExpectation\n edges?: GeoSpecNumericExpectation\n wires?: GeoSpecNumericExpectation\n faces?: GeoSpecNumericExpectation\n shells?: GeoSpecNumericExpectation\n solids?: GeoSpecNumericExpectation\n compounds?: GeoSpecNumericExpectation\n tolerance?: number\n}\n\n// STEP unit expectation accepted by `expectGeo(...).toHaveStepUnits(...)`\nGeoSpecStepUnitsExpectation: {\n unit: string\n}\n\n// Product-structure expectation accepted by `expectGeo(...).toHaveProductStructure(...)`\nGeoSpecProductStructureExpectation: {\n names?: string[]\n count?: GeoSpecNumericExpectation\n}\n\n// Planar-face expectation accepted by `expectGeo(...).toHavePlanarFace(...)`\nGeoSpecPlanarFaceExpectation: {\n normal: GeoSpecPointExpectation\n offset: number\n area?: GeoSpecNumericExpectation\n tolerance?: number\n}\n\n// Cylindrical-face expectation accepted by `expectGeo(...).toHaveCylindricalFace(...)`\nGeoSpecCylindricalFaceExpectation: {\n radius: number\n axis: 'x' | 'y' | 'z'\n tolerance?: number\n}\n\n// Circular-hole expectation accepted by `expectGeo(...).toHaveCircularHole(...)`\nGeoSpecCircularHoleExpectation: {\n diameter: number\n through?: boolean\n axis?: 'x' | 'y' | 'z'\n center?: GeoSpecPointExpectation\n tolerance?: number\n}\n\n// Circular-hole-pattern expectation accepted by `expectGeo(...).toHaveCircularHolePattern(...)`\nGeoSpecCircularHolePatternExpectation: {\n count: number\n holeDiameter: number\n boltCircleDiameter?: number\n axis?: 'x' | 'y' | 'z'\n center?: GeoSpecPointExpectation\n tolerance?: number\n}\n\n// Chamfer-feature expectation accepted by `expectGeo(...).toHaveChamferFeature(...)`\nGeoSpecChamferFeatureExpectation: {\n distance: number\n selection?: string\n tolerance?: number\n}\n\n// Fillet-feature expectation accepted by `expectGeo(...).toHaveFilletFeature(...)`\nGeoSpecFilletFeatureExpectation: {\n radius: number\n selection?: string\n tolerance?: number\n}\n\n// Minimum-wall-thickness expectation accepted by `expectGeo(...).toHaveMinimumWallThickness(...)`\nGeoSpecMinimumWallThicknessExpectation: {\n value: GeoSpecNumericExpectation\n tolerance?: number\n}\n\n// Void-continuity expectation accepted by `expectGeo(...).toHaveVoidContinuity(...)`\nGeoSpecVoidContinuityExpectation: {\n // Ordered waypoints (>= 1) known to lie in the void being proven\n path: GeoSpecVoidWaypoint[]\n // Occurrence names whose solids bound the void\n material?: string[]\n // Minimum required bottleneck cross-section (mm²), sampled\n minCrossSection?: number\n // Points that must NOT be reachable from the path void (isolation claim)\n isolatedFrom?: Vec3[]\n // Region bounded for the proof (subject frame)\n bounds?: {\n min: Vec3;\n max: Vec3;\n }\n}\n\n// Axis-keyed numeric expectation used by high-level geometry matchers\nGeoSpecAxisExpectation: {\n x?: number\n y?: number\n z?: number\n}\n\n// Shared scalar expectation used by geometry measurements\nGeoSpecNumericExpectation: number | {\n value?: number;\n greaterThan?: number;\n greaterThanOrEqual?: number;\n lessThan?: number;\n lessThanOrEqual?: number;\n}\n\n// A pair-specific component-interference check accepted by `expectGeo(...).toHaveNoComponentInterference(...)`\nGeoSpecComponentInterferencePairExpectation: {\n left: GeoSpecComponentSelector\n right: GeoSpecComponentSelector\n}\n\n// Intentional component interference allowance accepted by `expectGeo(...).toHaveNoComponentInterference(...)`\nGeoSpecComponentInterferenceAllowance: {\n kind?: 'intentionalInterference'\n left: GeoSpecComponentSelector\n right: GeoSpecComponentSelector\n maxVolume?: number\n reason: string\n}\n\n// Assembly occurrence rule accepted by `expectGeo(...).toHaveAssemblyOccurrences(...)`\nGeoSpecAssemblyOccurrenceExpectation: {\n name: GeoSpecComponentSelector\n count?: GeoSpecNumericExpectation\n bounds?: {\n within?: GeoSpecComponentSelector;\n min?: Vec3 | GeoSpecAxisExpectation;\n max?: Vec3 | GeoSpecAxisExpectation;\n center?: GeoSpecPointExpectation;\n tolerance?: number;\n }\n}\n\n// One spatial relationship accepted by `expectGeo(...).toHaveSpatialRelationships(...)`\nGeoSpecSpatialRelationshipExpectation: {\n id?: string\n kind: 'contact' | 'clearance' | 'coaxial' | 'concentric' | 'coplanar' | 'parallel' | 'perpendicular' | 'angle' | 'containment' | 'insertion' | 'interference'\n subject: GeoSpecGeometrySelector\n target: GeoSpecGeometrySelector\n tolerance?: number\n angularToleranceDegrees?: number\n // Expected angle in degrees for `kind\n angleDegrees?: number\n // Declared insertion axis (subject-frame direction) for `kind\n axis?: Vec3\n min?: number\n max?: number\n minVolume?: number\n maxVolume?: number\n reason?: string\n}\n\n// Diagnostic emitted by GeoSpec loaders, analyzers, and matchers\nGeometryDiagnostic: {\n code: KernelIssueCode | (string & {})\n severity: 'error' | 'warning' | 'info'\n message: string\n suggestion?: string\n spatial?: {\n min?: Vec3;\n max?: Vec3;\n center?: Vec3;\n }\n details?: unknown\n}\n\n// Point expectation accepted by center and feature matchers\nGeoSpecPointExpectation: Vec3 | GeoSpecAxisExpectation\n\n// One void-continuity waypoint\nGeoSpecVoidWaypoint: Vec3 | {\n occurrence: string;\n}\n\n// Direct geometry-source model load options\nLoadModelSourceOptions: {\n // Source geometry format\n format?: GeoSpecModelFormat\n // Explicit parameters recorded in provenance\n parameters?: Record<string, unknown>\n // Whether STEP loading should also produce mesh evidence\n mesh?: boolean\n // … 10 more members in the API reference: source, resources, rootDir, path, name, sourceUnit, stepStreaming, meshLinearTolerance, meshAngularToleranceDegrees, workUnitLimit\n}\n```\n\n## API reference\n\nTo 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.\n\n- `api-functions.md` — Functions\n- `api-constants.md` — Constants\n- `api-types.md` — Types\n- `api-classes.md` — Classes\n\nRead ranges, not whole files. Never copy a reference into a source file.\n",
10
- fingerprint: "efe3573b190312da73572be496f4052930d44071245e7ee367c5d870b26fda8c",
9
+ body: "---\nname: geospec-authoring\ndescription: Guides canonical GeoSpec geometry tests in TypeScript or JavaScript for every Tau kernel. Use for *.geospec.ts and *.geospec.js tests.\n---\n\n# GeoSpec authoring\n\nWrite tests before implementation; assert deterministic, measurable properties.\n\n## Test shape\n\n- Use `*.geospec.ts` or `*.geospec.js`. Import `describe`, `it` and `expectGeo` from `geospec`, and `loadModel` from `geospec/model`.\n- Await `loadModel`, then assert synchronously with `expectGeo(model)`. The host supplies the compiled binding; authoring does not select an engine.\n- Await or return the complete model-load chain from the test callback; detached future loads are not part of a completed test.\n- Omit `parameters` for model-code defaults; use `{ file, parameters }` for variants. Loaded subjects are opaque.\n- `loadModel({ file })` resolves `file` against the project root, the same root as every tool's `targetFile`; the result names that root as `projectRoot` where the host reports it, as `tau mcp` does. A suite in a subfolder names the model by its path from that root, or passes `rootDir`, the project-relative folder the model is in: `loadModel({ file: 'main.ts', rootDir: 'parts/gear' })` loads `parts/gear/main.ts`. A file the root does not hold refuses with `GEOSPEC_MODEL_SOURCE_NOT_FOUND`, which names the root and the path it looked for.\n\nCanonical TypeScript authoring:\n\n```ts\nimport { describe, expectGeo, it } from 'geospec';\nimport { loadModel } from 'geospec/model';\n\ndescribe('main geometry', () => {\n it('has the intended envelope', async () => {\n const model = await loadModel({ file: 'main.ts', parameters: { width: 120 } });\n expectGeo(model).toHaveBoundingBox({ size: { x: 120 }, tolerance: 1 });\n });\n});\n```\n\nSpecs are always TypeScript or JavaScript, whatever the model's kernel: `loadModel({ file })` evaluates `main.ts`, `main.tsx`, `main.py`, `main.scad`, `main.kcl` or `main.cs` through Tau's runtime. `test_model` discovers `*.geospec.ts` and `*.geospec.js` only.\n\nEvery matcher takes one expectation object:\n\n- Wrong: `expectGeo(model).toHaveVolume(5000, { tolerance: 5 })`. Correct: `expectGeo(model).toHaveVolume({ value: 5000, tolerance: 5 })`.\n- Wrong: `await expectGeo(model)…`. Correct: await `loadModel`, then assert synchronously.\n- Wrong: exact-feature matchers on a mesh kernel (Manifold, JSCAD, OpenSCAD, PicoGK, PicoVoxel). Correct: `toBeValidBrep`, `toHaveTopologyCounts`, the face, hole, pattern, chamfer, fillet and wall-thickness matchers, `toHaveStepUnits`, `toHaveProductStructure` and `toHaveVoidContinuity` need STEP BRep evidence and report unsupported on meshes; assert meshes with bounds, volume, surface area, connected components and `toBeWatertight`.\n\n## Loads and budgets\n\n- GeoSpec has no `beforeAll`. Write each `loadModel` inside its own `it`: within one run, identical loads (same file or code, parameters, format, tolerances and region) share one export and one admission. Each load keeps its own `loadId` and records `reused: true`, and a file is reused only while its source closure is unchanged.\n- `loadModel({ file, workUnitLimit })` sets the default claim budget for that subject, and `expectGeo(model, { workUnitLimit })` overrides it for one chain. The budget is a positive integer no greater than 512000000. A `MATCHER_TIMEOUT` refusal reports `details.limit` and, when measured, `details.used`; its `test_model` row (category `work-budget`) names in `limit.retry` the one `workUnitLimit` that can decide the claim, or `null` at the host maximum. Never treat the refusal as a pass.\n- `loadModel({ file, region: { min: [x, y, z], max: [x, y, z] } })` makes a separate claim about one millimetre box, never a stand-in for a whole-model claim. The kernel crops before export (PicoVoxel trims Voxels parts), and other kernels, STEP loads and unconfirmed crops refuse with a typed diagnostic. A cropped subject answers only bounding box, volume, surface area, mass and center of mass of its region, and its assertions record the region. Every other matcher on it refuses with `GEOSPEC_REGION_WHOLE_MODEL_CLAIM`. Name the region in the test, and keep whole-model claims on whole-model loads.\n- A host or engine limit leaves a claim undecided, never false: `test_model` reports it as inconclusive with category `analysis-limit`, `resource-limit` or `work-budget` and a typed `limit` naming the limit and its numbers. Keep the model as designed: never coarsen, shrink or crop it to fit. Only a `work-budget` row's `limit.retry` is a retry, and `testTimeout` only answers a `timeout` row; report every other limit row as not decided at this capacity.\n- `toHaveCenterOfMass({ point, tolerance })` takes an exact point. Per-axis ranges such as `{ y: { greaterThan: 1 } }` are refused.\n\n## Ceilings\n\nFixed in this release; design within them, and report a claim that meets one as not decided.\n\n| Ceiling | Value | Where an agent meets it |\n| ------------------------------------- | -------------------- | --------------------------------------------------------------------------------------------------------------------------------- |\n| `maxSubjectBytes`, `maxResourceBytes` | 64 MiB each | A mesh `loadModel({ file })` exports about 72 bytes per triangle, so admission refuses near 930,000 triangles (`resource-limit`). |\n| `maxTotalBinaryBytes` | 128 MiB | All subjects of one load together. |\n| `maxTriangles`, `maxVertices` | 4,000,000, 2,000,000 | A decoded mesh. |\n| `continuousEvidenceBytes` | 32 MiB | `toHaveNoComponentInterference` on a large assembly (`analysis-limit`). |\n| `workUnitLimit` | 512000000 at most | Any claim; the only limit an argument raises. |\n\nLoad `format: 'step'` only for the exact-BRep matchers above; every other matcher answers on the cheaper mesh.\n\n## Coverage\n\nBounds and physical properties are insufficient. Cover major components, named features, variants, dimensions/positions, disjoint counts, closure, interference and supported exact features. Explicitly report unsupported requirements; proxies cannot fulfill them.\n\n- `toHaveBoundingBox`: size/position.\n- `toHaveConnectedComponents`: qualified material connectivity; visual touching cannot justify tolerance changes.\n- `toBeWatertight`: closed edge incidence, not manifold validity, fusion or material connectivity. Bounds prove none of these. Missing evidence is unsupported.\n- `toHaveSurfaceArea`, `toHaveVolume`, `toHaveCenterOfMass`, `toHaveMass`: physical measurements.\n- `toHaveNoComponentInterference`: overlap; allow deliberate press fits.\n- `loadModel({ file, format: 'step' })`: use BRep evidence for supported topology and feature assertions. Missing occurrence, interference, clearance, containment, lumen, wall, section or motion evidence is unsupported, not a pass or an envelope substitute.\n\nTest assemblies and independent units; preserve sibling coverage when adding files. Non-top-level geometry needs kernel export/invocation, not test removal.\n\nFix geometry at its root; never weaken tolerances, delete assertions, or reduce detail to pass.\n\n`public-api-index.md` covers the host and framework API; authoring needs only the Core API below and `api-*` files.\n\n## Core API\n\nThe symbols real Tau models use most, as verbatim declarations. Anything not shown is in the API reference below.\n\n### Functions\n\n```ts\n// Start a geometry assertion chain\nexport declare function expectGeo(subject: GeoSpecSubject, options?: GeoSpecExpectOptions): GeoSpecMatcher;\n\n// A model admitted by one live GeoSpec host scope\nGeoSpecSubject: {\n readonly [subjectBrand]: true\n}\n\n// Per-chain options accepted by `expectGeo(subject, options)`\nGeoSpecExpectOptions: {\n // Deterministic work-unit budget for every claim in this chain\n readonly workUnitLimit?: number\n}\n\n// Load a CAD model into GeoSpec evidence\nexport declare function loadModel<Code extends Record<string, string> = Record<string, string>>(_options: LoadModelOptions<Code>): Promise<GeoSpecSubject>;\n\n// Options accepted by {@link import ('./load-model.js').loadModel}\nLoadModelOptions: LoadModelSourceOptions | LoadModelCodeOptions<Code> | LoadModelFileOptions\n // Project-relative folder `file` resolves in, for a suite that loads from somewhere other than…\n rootDir?: string\n // Geometry format to export\n format?: GeoSpecModelFormat\n // Explicit parameters passed to the exporter\n parameters?: Record<string, unknown>\n // STEP reader strategy used for STEP exports\n stepStreaming?: StepStreamingMode\n // Whether STEP loading should also produce mesh evidence\n mesh?: boolean\n // Linear tolerance used while meshing exact BRep evidence\n meshLinearTolerance?: number\n // Angular tolerance in degrees used while meshing exact BRep evidence\n meshAngularToleranceDegrees?: number\n // Default work-unit budget for every claim on this subject\n workUnitLimit?: number\n\n// Geometry formats accepted by {@link import ('./load-model.js').loadModel}\nGeoSpecModelFormat: MeshFileFormat | 'step' | 'stp'\n\n// GeoSpec test helper used inside VM-executed test modules\nexport declare function it(name: string, function_: GeoSpecTestCallback): void;\n skip(name: string, function_?: GeoSpecTestCallback): void;\n\n// GeoSpec suite helper used inside VM-executed test modules\nexport declare function describe(name: string, function_: GeoSpecTestCallback): void;\n skip(name: string, function_?: GeoSpecTestCallback): void;\n\n// Alias for {@link it}\nexport declare function test(name: string, function_: GeoSpecTestCallback): void;\n skip(name: string, function_?: GeoSpecTestCallback): void;\n```\n\n### Types\n\n```ts\n// Assertion chain returned by `expectGeo(subject)`\nGeoSpecMatcher: {\n // Core-owned negation\n readonly not: Omit<GeoSpecMatcher, 'not'>\n // Assert the fixed rational plate contract\n toSatisfyRationalPlate(): GeoSpecAssertion;\n // Assert the fixed parallel-plane distance contract\n toSatisfyParallelPlaneDistance(): GeoSpecAssertion;\n // Assert axis-aligned bounds, size, or center for a loaded geometry subject\n toHaveBoundingBox(first: Vec3 | GeoSpecBoundingBoxExpectation, second?: Vec3): GeoSpecAssertion;\n // Assert how many spatially disjoint chunks the mesh contains\n toHaveConnectedComponents(expected: GeoSpecConnectedComponentsExpectation): GeoSpecAssertion;\n // Assert closed mesh edge incidence\n toBeWatertight(): GeoSpecAssertion;\n // Assert that separate assembly components do not occupy the same solid volume\n toHaveNoComponentInterference(expected?: GeoSpecComponentInterferenceExpectation): GeoSpecAssertion;\n // Assert that named assembly occurrences exist with expected counts and bounds\n toHaveAssemblyOccurrences(expected: GeoSpecAssemblyOccurrencesExpectation): GeoSpecAssertion;\n // Assert that selected entities satisfy declared spatial relationships\n toHaveSpatialRelationships(expected: GeoSpecSpatialRelationshipsExpectation): GeoSpecAssertion;\n // Assert rendered mesh evidence is internally trustworthy for downstream checks\n toHaveMeshIntegrity(expected: GeoSpecMeshIntegrityExpectation): GeoSpecAssertion;\n // Assert that the subject carries no diagnostics at the rejected severities\n toHaveNoDiagnostics(expected?: GeoSpecNoDiagnosticsExpectation): GeoSpecAssertion;\n // Assert total surface area, preferring exact BRep mass properties when available\n toHaveSurfaceArea(expected: GeoSpecSurfaceAreaExpectation): GeoSpecAssertion;\n // Assert enclosed volume, preferring exact BRep mass properties when available\n toHaveVolume(expected: GeoSpecVolumeExpectation): GeoSpecAssertion;\n // Assert mass derived from exact mass properties or volume times density\n toHaveMass(expected: GeoSpecMassExpectation): GeoSpecAssertion;\n // Assert the center of mass or mesh-derived centroid for a closed subject\n toHaveCenterOfMass(expected: GeoSpecCenterOfMassExpectation): GeoSpecAssertion;\n // Assert that exact BRep evidence reports a valid shape\n toBeValidBrep(expected?: GeoSpecValidBrepExpectation): GeoSpecAssertion;\n // Assert exact BRep topology counts\n toHaveTopologyCounts(expected: GeoSpecTopologyCountsExpectation): GeoSpecAssertion;\n // Assert the STEP unit evidence\n toHaveStepUnits(expected: GeoSpecStepUnitsExpectation): GeoSpecAssertion;\n // Assert STEP product-structure evidence\n toHaveProductStructure(expected: GeoSpecProductStructureExpectation): GeoSpecAssertion;\n // Assert that BRep evidence contains a planar face matching the requested constraints\n toHavePlanarFace(expected: GeoSpecPlanarFaceExpectation): GeoSpecAssertion;\n // Assert that BRep evidence contains a cylindrical face with the requested radius and axis\n toHaveCylindricalFace(expected: GeoSpecCylindricalFaceExpectation): GeoSpecAssertion;\n // Assert that BRep evidence contains a circular hole matching diameter, center, and axis\n toHaveCircularHole(expected: GeoSpecCircularHoleExpectation): GeoSpecAssertion;\n // Assert that BRep evidence contains a repeated circular-hole pattern\n toHaveCircularHolePattern(expected: GeoSpecCircularHolePatternExpectation): GeoSpecAssertion;\n // Assert that BRep evidence contains a chamfer feature with the requested distance\n toHaveChamferFeature(expected: GeoSpecChamferFeatureExpectation): GeoSpecAssertion;\n // Assert that BRep evidence contains a fillet feature with the requested radius\n toHaveFilletFeature(expected: GeoSpecFilletFeatureExpectation): GeoSpecAssertion;\n // Assert that BRep evidence reports a minimum wall thickness satisfying the expectation\n toHaveMinimumWallThickness(expected: GeoSpecMinimumWallThicknessExpectation): GeoSpecAssertion;\n // Assert that the declared waypoints share one connected void, stay isolated from the declared…\n toHaveVoidContinuity(expected: GeoSpecVoidContinuityExpectation): GeoSpecAssertion;\n}\n\n// Numeric 3D vector\nVec3: readonly [number, number, number]\n\n// Bounding-box expectation accepted by `expectGeo(...).toHaveBoundingBox(...)`\nGeoSpecBoundingBoxExpectation: {\n min?: Vec3 | Partial<Record<keyof GeoSpecAxisExpectation, GeoSpecNumericExpectation>>\n max?: Vec3 | Partial<Record<keyof GeoSpecAxisExpectation, GeoSpecNumericExpectation>>\n size?: Vec3 | Partial<Record<keyof GeoSpecAxisExpectation, GeoSpecNumericExpectation>>\n center?: Vec3 | Partial<Record<keyof GeoSpecAxisExpectation, GeoSpecNumericExpectation>>\n tolerance?: number\n}\n\n// Connected-components expectation accepted by `expectGeo(...).toHaveConnectedComponents(...)`\nGeoSpecConnectedComponentsExpectation: {\n count: number\n tolerance?: number\n toleranceMm?: number\n}\n\n// Component-interference expectation accepted by `expectGeo(...).toHaveNoComponentInterference(...)`\nGeoSpecComponentInterferenceExpectation: {\n tolerance?: number\n pairs?: GeoSpecComponentInterferencePairExpectation[]\n allowances?: GeoSpecComponentInterferenceAllowance[]\n}\n\n// Assembly occurrence expectation accepted by `expectGeo(...).toHaveAssemblyOccurrences(...)`\nGeoSpecAssemblyOccurrencesExpectation: {\n occurrences: GeoSpecAssemblyOccurrenceExpectation[]\n uniqueNames?: boolean\n}\n\n// Spatial relationship expectation accepted by `expectGeo(...).toHaveSpatialRelationships(...)`\nGeoSpecSpatialRelationshipsExpectation: {\n relationships: GeoSpecSpatialRelationshipExpectation[]\n}\n\n// Mesh integrity expectation accepted by `expectGeo(...).toHaveMeshIntegrity(...)`\nGeoSpecMeshIntegrityExpectation: {\n finitePositions?: boolean\n degenerateTriangles?: {\n count?: number;\n maxCount?: number;\n areaTolerance?: number;\n }\n duplicateFaces?: {\n count?: number;\n maxCount?: number;\n }\n watertight?: boolean\n triangleCount?: GeoSpecNumericExpectation\n}\n\n// Diagnostic severities rejected by `expectGeo(...).toHaveNoDiagnostics(...)`\nGeoSpecNoDiagnosticsExpectation: {\n severities?: Array<GeometryDiagnostic['severity']>\n}\n\n// Surface-area expectation accepted by `expectGeo(...).toHaveSurfaceArea(...)`\nGeoSpecSurfaceAreaExpectation: {\n value: number | GeoSpecNumericExpectation\n tolerance?: number\n}\n\n// Volume expectation accepted by `expectGeo(...).toHaveVolume(...)`\nGeoSpecVolumeExpectation: {\n value: number | GeoSpecNumericExpectation\n tolerance?: number\n}\n\n// Mass expectation accepted by `expectGeo(...).toHaveMass(...)`\nGeoSpecMassExpectation: {\n value: number | GeoSpecNumericExpectation\n density?: number\n tolerance?: number\n}\n\n// Center-of-mass expectation accepted by `expectGeo(...).toHaveCenterOfMass(...)`\nGeoSpecCenterOfMassExpectation: {\n // Exact expected point in millimetres\n point: GeoSpecPointExpectation\n tolerance?: number\n}\n\n// Exact BRep validity expectation accepted by `expectGeo(...).toBeValidBrep(...)`\nGeoSpecValidBrepExpectation: {\n maxTolerance?: number\n freeBounds?: {\n count?: GeoSpecNumericExpectation;\n }\n minEdgeLength?: number\n sameParameter?: boolean\n closedShells?: boolean\n closedWires?: boolean\n}\n\n// Topology-count expectation accepted by `expectGeo(...).toHaveTopologyCounts(...)`\nGeoSpecTopologyCountsExpectation: {\n vertices?: GeoSpecNumericExpectation\n edges?: GeoSpecNumericExpectation\n wires?: GeoSpecNumericExpectation\n faces?: GeoSpecNumericExpectation\n shells?: GeoSpecNumericExpectation\n solids?: GeoSpecNumericExpectation\n compounds?: GeoSpecNumericExpectation\n tolerance?: number\n}\n\n// STEP unit expectation accepted by `expectGeo(...).toHaveStepUnits(...)`\nGeoSpecStepUnitsExpectation: {\n unit: string\n}\n\n// Product-structure expectation accepted by `expectGeo(...).toHaveProductStructure(...)`\nGeoSpecProductStructureExpectation: {\n names?: string[]\n count?: GeoSpecNumericExpectation\n}\n\n// Planar-face expectation accepted by `expectGeo(...).toHavePlanarFace(...)`\nGeoSpecPlanarFaceExpectation: {\n normal: GeoSpecPointExpectation\n offset: number\n area?: GeoSpecNumericExpectation\n tolerance?: number\n}\n\n// Cylindrical-face expectation accepted by `expectGeo(...).toHaveCylindricalFace(...)`\nGeoSpecCylindricalFaceExpectation: {\n radius: number\n axis: 'x' | 'y' | 'z'\n tolerance?: number\n}\n\n// Circular-hole expectation accepted by `expectGeo(...).toHaveCircularHole(...)`\nGeoSpecCircularHoleExpectation: {\n diameter: number\n through?: boolean\n axis?: 'x' | 'y' | 'z'\n center?: GeoSpecPointExpectation\n tolerance?: number\n}\n\n// Circular-hole-pattern expectation accepted by `expectGeo(...).toHaveCircularHolePattern(...)`\nGeoSpecCircularHolePatternExpectation: {\n count: number\n holeDiameter: number\n boltCircleDiameter?: number\n axis?: 'x' | 'y' | 'z'\n center?: GeoSpecPointExpectation\n tolerance?: number\n}\n\n// Chamfer-feature expectation accepted by `expectGeo(...).toHaveChamferFeature(...)`\nGeoSpecChamferFeatureExpectation: {\n distance: number\n selection?: string\n tolerance?: number\n}\n\n// Fillet-feature expectation accepted by `expectGeo(...).toHaveFilletFeature(...)`\nGeoSpecFilletFeatureExpectation: {\n radius: number\n selection?: string\n tolerance?: number\n}\n\n// Minimum-wall-thickness expectation accepted by `expectGeo(...).toHaveMinimumWallThickness(...)`\nGeoSpecMinimumWallThicknessExpectation: {\n value: GeoSpecNumericExpectation\n tolerance?: number\n}\n\n// Void-continuity expectation accepted by `expectGeo(...).toHaveVoidContinuity(...)`\nGeoSpecVoidContinuityExpectation: {\n // Ordered waypoints (>= 1) known to lie in the void being proven\n path: GeoSpecVoidWaypoint[]\n // Occurrence names whose solids bound the void\n material?: string[]\n // Minimum required bottleneck cross-section (mm²), sampled\n minCrossSection?: number\n // Points that must NOT be reachable from the path void (isolation claim)\n isolatedFrom?: Vec3[]\n // Region bounded for the proof (subject frame)\n bounds?: {\n min: Vec3;\n max: Vec3;\n }\n}\n\n// Axis-keyed numeric expectation used by high-level geometry matchers\nGeoSpecAxisExpectation: {\n x?: number\n y?: number\n z?: number\n}\n\n// Shared scalar expectation used by geometry measurements\nGeoSpecNumericExpectation: number | {\n value?: number;\n greaterThan?: number;\n greaterThanOrEqual?: number;\n lessThan?: number;\n lessThanOrEqual?: number;\n}\n\n// A pair-specific component-interference check accepted by `expectGeo(...).toHaveNoComponentInterference(...)`\nGeoSpecComponentInterferencePairExpectation: {\n left: GeoSpecComponentSelector\n right: GeoSpecComponentSelector\n}\n\n// Intentional component interference allowance accepted by `expectGeo(...).toHaveNoComponentInterference(...)`\nGeoSpecComponentInterferenceAllowance: {\n kind?: 'intentionalInterference'\n left: GeoSpecComponentSelector\n right: GeoSpecComponentSelector\n maxVolume?: number\n reason: string\n}\n\n// Assembly occurrence rule accepted by `expectGeo(...).toHaveAssemblyOccurrences(...)`\nGeoSpecAssemblyOccurrenceExpectation: {\n name: GeoSpecComponentSelector\n count?: GeoSpecNumericExpectation\n bounds?: {\n within?: GeoSpecComponentSelector;\n min?: Vec3 | GeoSpecAxisExpectation;\n max?: Vec3 | GeoSpecAxisExpectation;\n center?: GeoSpecPointExpectation;\n tolerance?: number;\n }\n}\n\n// One spatial relationship accepted by `expectGeo(...).toHaveSpatialRelationships(...)`\nGeoSpecSpatialRelationshipExpectation: {\n id?: string\n kind: 'contact' | 'clearance' | 'coaxial' | 'concentric' | 'coplanar' | 'parallel' | 'perpendicular' | 'angle' | 'containment' | 'insertion' | 'interference'\n subject: GeoSpecGeometrySelector\n target: GeoSpecGeometrySelector\n tolerance?: number\n angularToleranceDegrees?: number\n // Expected angle in degrees for `kind\n angleDegrees?: number\n // Declared insertion axis (subject-frame direction) for `kind\n axis?: Vec3\n min?: number\n max?: number\n minVolume?: number\n maxVolume?: number\n reason?: string\n}\n\n// Diagnostic emitted by GeoSpec loaders, analyzers, and matchers\nGeometryDiagnostic: {\n code: KernelIssueCode | (string & {})\n severity: 'error' | 'warning' | 'info'\n message: string\n suggestion?: string\n spatial?: {\n min?: Vec3;\n max?: Vec3;\n center?: Vec3;\n }\n details?: unknown\n}\n\n// Point expectation accepted by center and feature matchers\nGeoSpecPointExpectation: Vec3 | GeoSpecAxisExpectation\n\n// One void-continuity waypoint\nGeoSpecVoidWaypoint: Vec3 | {\n occurrence: string;\n}\n\n// Direct geometry-source model load options\nLoadModelSourceOptions: {\n // Source geometry format\n format?: GeoSpecModelFormat\n // Explicit parameters recorded in provenance\n parameters?: Record<string, unknown>\n // Whether STEP loading should also produce mesh evidence\n mesh?: boolean\n // … 10 more members in the API reference: source, resources, rootDir, path, name, sourceUnit, stepStreaming, meshLinearTolerance, meshAngularToleranceDegrees, workUnitLimit\n}\n```\n\n## API reference\n\nTo 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.\n\n- `api-functions.md` — Functions\n- `api-constants.md` — Constants\n- `api-types.md` — Types\n- `api-types-2.md` — Types (2)\n- `api-classes.md` — Classes\n\nRead ranges, not whole files. Never copy a reference into a source file.\n",
10
+ fingerprint: "5e704f16193aa6d01335dee5374f0fec90037d4651613996896c78d3a2e303ff",
11
11
  files: Object.freeze([
12
- Object.freeze({ path: "SKILL.md", url: new URL("./geospec-authoring/SKILL.md", import.meta.url).href, byteLength: 23624, lineCount: 496, contentKind: 'text', mediaType: 'text/markdown', sha256: "48e106b1c5274fbbbbf960f3c2a7d39865cd4533dd2b2ba75c8f642a7d08ed94" }),
13
- Object.freeze({ path: "api-index.md", url: new URL("./geospec-authoring/api-index.md", import.meta.url).href, byteLength: 30639, lineCount: 386, contentKind: 'text', mediaType: 'text/markdown', sha256: "f7eec6cf13bc3e30f12040e83a318a39eb04517c657c206355d6428764f7d8d9" }),
12
+ Object.freeze({ path: "SKILL.md", url: new URL("./geospec-authoring/SKILL.md", import.meta.url).href, byteLength: 23657, lineCount: 497, contentKind: 'text', mediaType: 'text/markdown', sha256: "484351daa87c73bc14adbe04ee2ffc961b3c28fd388658cd2174e89d884fea5b" }),
13
+ Object.freeze({ path: "api-index.md", url: new URL("./geospec-authoring/api-index.md", import.meta.url).href, byteLength: 30670, lineCount: 389, contentKind: 'text', mediaType: 'text/markdown', sha256: "3b5405c4c680c1e5d97f519f59c00683ab9702adc17be9f518426674469734e9" }),
14
14
  Object.freeze({ path: "api-functions.md", url: new URL("./geospec-authoring/api-functions.md", import.meta.url).href, byteLength: 1946, lineCount: 43, contentKind: 'text', mediaType: 'text/markdown', sha256: "b8c0ce6fb9a274b59795b7ca4254d68296cd04d6c7e8124d21f74feb071e960b" }),
15
15
  Object.freeze({ path: "api-constants.md", url: new URL("./geospec-authoring/api-constants.md", import.meta.url).href, byteLength: 1057, lineCount: 17, contentKind: 'text', mediaType: 'text/markdown', sha256: "42c29ab127efb592c0cd7c4d2024d6e2aea8315bec78e476f972166c1b8c1c6b" }),
16
- Object.freeze({ path: "api-types.md", url: new URL("./geospec-authoring/api-types.md", import.meta.url).href, byteLength: 62113, lineCount: 1837, contentKind: 'text', mediaType: 'text/markdown', sha256: "9a48ee5e71d16828061efbaafe26c71a3ef1a7694173057714cbf6803fcea162" }),
16
+ Object.freeze({ path: "api-types.md", url: new URL("./geospec-authoring/api-types.md", import.meta.url).href, byteLength: 59196, lineCount: 1755, contentKind: 'text', mediaType: 'text/markdown', sha256: "5a7248985515201bb7029f89f7373b1de74f65078a01c6119e526582b4f64085" }),
17
+ Object.freeze({ path: "api-types-2.md", url: new URL("./geospec-authoring/api-types-2.md", import.meta.url).href, byteLength: 3210, lineCount: 86, contentKind: 'text', mediaType: 'text/markdown', sha256: "6d75581152c13419ec617081b0b7cd87abd1ffbaf4e8c5567cb3b225a7d35e04" }),
17
18
  Object.freeze({ path: "api-classes.md", url: new URL("./geospec-authoring/api-classes.md", import.meta.url).href, byteLength: 550, lineCount: 14, contentKind: 'text', mediaType: 'text/markdown', sha256: "d34a48498cfd33aca05e2c5c1059ca3e2d1bec86046fbc75928d16b375fcae30" }),
18
- Object.freeze({ path: "public-api-index.md", url: new URL("./geospec-authoring/public-api-index.md", import.meta.url).href, byteLength: 70467, lineCount: 912, contentKind: 'text', mediaType: 'text/markdown', sha256: "5da9fbc26d351f05b7a3e611c1c8782d24f66790262c4c1edbf8f4b5172135b8" }),
19
- Object.freeze({ path: "public-api-functions.md", url: new URL("./geospec-authoring/public-api-functions.md", import.meta.url).href, byteLength: 11832, lineCount: 223, contentKind: 'text', mediaType: 'text/markdown', sha256: "10524a820e3d718248f9f323a74acca652f69bbcf69708d11148600c6176b054" }),
19
+ Object.freeze({ path: "public-api-index.md", url: new URL("./geospec-authoring/public-api-index.md", import.meta.url).href, byteLength: 73854, lineCount: 951, contentKind: 'text', mediaType: 'text/markdown', sha256: "ce02af19387c7de09717c6754d4fc17ef6429c509ef803493a2866e28d39b66f" }),
20
+ Object.freeze({ path: "public-api-functions.md", url: new URL("./geospec-authoring/public-api-functions.md", import.meta.url).href, byteLength: 15034, lineCount: 264, contentKind: 'text', mediaType: 'text/markdown', sha256: "d24f96454d432789ebff1b73278e790a25df6cd7db87f407f0e6ca7fa3a26d88" }),
20
21
  Object.freeze({ path: "public-api-constants.md", url: new URL("./geospec-authoring/public-api-constants.md", import.meta.url).href, byteLength: 2521, lineCount: 52, contentKind: 'text', mediaType: 'text/markdown', sha256: "8d7ecd06cd47616d81d6b5ad0315eee3cb1ed980d6527d6e2edf40c44231d871" }),
21
- Object.freeze({ path: "public-api-types.md", url: new URL("./geospec-authoring/public-api-types.md", import.meta.url).href, byteLength: 63447, lineCount: 2060, contentKind: 'text', mediaType: 'text/markdown', sha256: "9c25125375b947a39454074509f376017d2ae14b30c00aa26a7adb7be8ccc1ad" }),
22
- Object.freeze({ path: "public-api-types-2.md", url: new URL("./geospec-authoring/public-api-types-2.md", import.meta.url).href, byteLength: 55023, lineCount: 1496, contentKind: 'text', mediaType: 'text/markdown', sha256: "eb42a4f1f1fae85c6e4694caa81db95a9f083f46d7150d8cef71384ff065cc2e" }),
23
- Object.freeze({ path: "public-api-types-3.md", url: new URL("./geospec-authoring/public-api-types-3.md", import.meta.url).href, byteLength: 9469, lineCount: 295, contentKind: 'text', mediaType: 'text/markdown', sha256: "0b2798e3b55ab76ae98ed2b08ab6befe146c436c0c05fa3b83117c5cea736245" }),
22
+ Object.freeze({ path: "public-api-types.md", url: new URL("./geospec-authoring/public-api-types.md", import.meta.url).href, byteLength: 63658, lineCount: 2060, contentKind: 'text', mediaType: 'text/markdown', sha256: "f80b75d3f3b7edca2245e3d549030125477f8ba404875ee8e4a7b9edf90c18f4" }),
23
+ Object.freeze({ path: "public-api-types-2.md", url: new URL("./geospec-authoring/public-api-types-2.md", import.meta.url).href, byteLength: 53802, lineCount: 1422, contentKind: 'text', mediaType: 'text/markdown', sha256: "69965c3798878d951f1c52224e6e26712f8d4dbd88e4e911ca6ccd70a6bcd8b6" }),
24
+ Object.freeze({ path: "public-api-types-3.md", url: new URL("./geospec-authoring/public-api-types-3.md", import.meta.url).href, byteLength: 18307, lineCount: 575, contentKind: 'text', mediaType: 'text/markdown', sha256: "e241bc2a741661c4f12698f0a351336999f7526a15bb5e117ab45ce4c34b254a" }),
24
25
  Object.freeze({ path: "public-api-classes.md", url: new URL("./geospec-authoring/public-api-classes.md", import.meta.url).href, byteLength: 1024, lineCount: 23, contentKind: 'text', mediaType: 'text/markdown', sha256: "569639b75b3a3fae86e3bcbe3dc61a746ddd67cb4dec7ccb6374556d419d02a9" })
25
26
  ]),
26
27
  }),
package/agent/skills.json CHANGED
@@ -4,7 +4,7 @@
4
4
  "slug": "geospec-authoring",
5
5
  "name": "GeoSpec authoring",
6
6
  "description": "Guides canonical GeoSpec geometry tests in TypeScript or JavaScript for every Tau kernel. Use for *.geospec.ts and *.geospec.js tests.",
7
- "version": "0.1.0-beta.8",
7
+ "version": "0.1.0-beta.9",
8
8
  "whenToUse": "Use before creating or editing *.geospec.ts or *.geospec.js tests, for a model in any kernel.",
9
9
  "directory": "geospec-authoring",
10
10
  "files": [
@@ -13,6 +13,7 @@
13
13
  "api-functions.md",
14
14
  "api-constants.md",
15
15
  "api-types.md",
16
+ "api-types-2.md",
16
17
  "api-classes.md",
17
18
  "public-api-index.md",
18
19
  "public-api-functions.md",
@@ -22,7 +23,7 @@
22
23
  "public-api-types-3.md",
23
24
  "public-api-classes.md"
24
25
  ],
25
- "body": "---\nname: geospec-authoring\ndescription: Guides canonical GeoSpec geometry tests in TypeScript or JavaScript for every Tau kernel. Use for *.geospec.ts and *.geospec.js tests.\n---\n\n# GeoSpec authoring\n\nWrite tests before implementation; assert deterministic, measurable properties.\n\n## Test shape\n\n- Use `*.geospec.ts` or `*.geospec.js`. Import `describe`, `it` and `expectGeo` from `geospec`, and `loadModel` from `geospec/model`.\n- Await `loadModel`, then assert synchronously with `expectGeo(model)`. The host supplies the compiled binding; authoring does not select an engine.\n- Await or return the complete model-load chain from the test callback; detached future loads are not part of a completed test.\n- Omit `parameters` for model-code defaults; use `{ file, parameters }` for variants. Loaded subjects are opaque.\n- `loadModel({ file })` resolves `file` against the project root, the same root as every tool's `targetFile`; the result names that root as `projectRoot` where the host reports it, as `tau mcp` does. A suite in a subfolder names the model by its path from that root, or passes `rootDir`, the project-relative folder the model is in: `loadModel({ file: 'main.ts', rootDir: 'parts/gear' })` loads `parts/gear/main.ts`. A file the root does not hold refuses with `GEOSPEC_MODEL_SOURCE_NOT_FOUND`, which names the root and the path it looked for.\n\nCanonical TypeScript authoring:\n\n```ts\nimport { describe, expectGeo, it } from 'geospec';\nimport { loadModel } from 'geospec/model';\n\ndescribe('main geometry', () => {\n it('has the intended envelope', async () => {\n const model = await loadModel({ file: 'main.ts', parameters: { width: 120 } });\n expectGeo(model).toHaveBoundingBox({ size: { x: 120 }, tolerance: 1 });\n });\n});\n```\n\nSpecs are always TypeScript or JavaScript, whatever the model's kernel: `loadModel({ file })` evaluates `main.ts`, `main.tsx`, `main.py`, `main.scad`, `main.kcl` or `main.cs` through Tau's runtime. `test_model` discovers `*.geospec.ts` and `*.geospec.js` only.\n\nEvery matcher takes one expectation object:\n\n- Wrong: `expectGeo(model).toHaveVolume(5000, { tolerance: 5 })`. Correct: `expectGeo(model).toHaveVolume({ value: 5000, tolerance: 5 })`.\n- Wrong: `await expectGeo(model)…`. Correct: await `loadModel`, then assert synchronously.\n- Wrong: exact-feature matchers on a mesh kernel (Manifold, JSCAD, OpenSCAD, PicoGK, PicoVoxel). Correct: `toBeValidBrep`, `toHaveTopologyCounts`, the face, hole, pattern, chamfer, fillet and wall-thickness matchers, `toHaveStepUnits`, `toHaveProductStructure` and `toHaveVoidContinuity` need STEP BRep evidence and report unsupported on meshes; assert meshes with bounds, volume, surface area, connected components and `toBeWatertight`.\n\n## Loads and budgets\n\n- GeoSpec has no `beforeAll`. Write each `loadModel` inside its own `it`: within one run, identical loads (same file or code, parameters, format, tolerances and region) share one export and one admission. Each load keeps its own `loadId` and records `reused: true`, and a file is reused only while its source closure is unchanged.\n- `loadModel({ file, workUnitLimit })` sets the default claim budget for that subject, and `expectGeo(model, { workUnitLimit })` overrides it for one chain. The budget is a positive integer no greater than 512000000. A `MATCHER_TIMEOUT` refusal reports `details.limit` and, when measured, `details.used`; its `test_model` row (category `work-budget`) names in `limit.retry` the one `workUnitLimit` that can decide the claim, or `null` at the host maximum. Never treat the refusal as a pass.\n- `loadModel({ file, region: { min: [x, y, z], max: [x, y, z] } })` makes a separate claim about one millimetre box, never a stand-in for a whole-model claim. The kernel crops before export (PicoVoxel trims Voxels parts), and other kernels, STEP loads and unconfirmed crops refuse with a typed diagnostic. A cropped subject answers only bounding box, volume, surface area, mass and center of mass of its region, and its assertions record the region. Every other matcher on it refuses with `GEOSPEC_REGION_WHOLE_MODEL_CLAIM`. Name the region in the test, and keep whole-model claims on whole-model loads.\n- A host or engine limit leaves a claim undecided, never false: `test_model` reports it as inconclusive with category `analysis-limit`, `resource-limit` or `work-budget` and a typed `limit` naming the limit and its numbers. Keep the model as designed: never coarsen, shrink or crop it to fit. Only a `work-budget` row's `limit.retry` is a retry, and `testTimeout` only answers a `timeout` row; report every other limit row as not decided at this capacity.\n- `toHaveCenterOfMass({ point, tolerance })` takes an exact point. Per-axis ranges such as `{ y: { greaterThan: 1 } }` are refused.\n\n## Ceilings\n\nFixed in this release; design within them, and report a claim that meets one as not decided.\n\n| Ceiling | Value | Where an agent meets it |\n| ------------------------------------- | -------------------- | --------------------------------------------------------------------------------------------------------------------------------- |\n| `maxSubjectBytes`, `maxResourceBytes` | 64 MiB each | A mesh `loadModel({ file })` exports about 72 bytes per triangle, so admission refuses near 930,000 triangles (`resource-limit`). |\n| `maxTotalBinaryBytes` | 128 MiB | All subjects of one load together. |\n| `maxTriangles`, `maxVertices` | 4,000,000, 2,000,000 | A decoded mesh. |\n| `continuousEvidenceBytes` | 32 MiB | `toHaveNoComponentInterference` on a large assembly (`analysis-limit`). |\n| `workUnitLimit` | 512000000 at most | Any claim; the only limit an argument raises. |\n\nLoad `format: 'step'` only for the exact-BRep matchers above; every other matcher answers on the cheaper mesh.\n\n## Coverage\n\nBounds and physical properties are insufficient. Cover major components, named features, variants, dimensions/positions, disjoint counts, closure, interference and supported exact features. Explicitly report unsupported requirements; proxies cannot fulfill them.\n\n- `toHaveBoundingBox`: size/position.\n- `toHaveConnectedComponents`: qualified material connectivity; visual touching cannot justify tolerance changes.\n- `toBeWatertight`: closed edge incidence, not manifold validity, fusion or material connectivity. Bounds prove none of these. Missing evidence is unsupported.\n- `toHaveSurfaceArea`, `toHaveVolume`, `toHaveCenterOfMass`, `toHaveMass`: physical measurements.\n- `toHaveNoComponentInterference`: overlap; allow deliberate press fits.\n- `loadModel({ file, format: 'step' })`: use BRep evidence for supported topology and feature assertions. Missing occurrence, interference, clearance, containment, lumen, wall, section or motion evidence is unsupported, not a pass or an envelope substitute.\n\nTest assemblies and independent units; preserve sibling coverage when adding files. Non-top-level geometry needs kernel export/invocation, not test removal.\n\nFix geometry at its root; never weaken tolerances, delete assertions, or reduce detail to pass.\n\n`public-api-index.md` covers the host and framework API; authoring needs only the Core API below and `api-*` files.\n\n## Core API\n\nThe symbols real Tau models use most, as verbatim declarations. Anything not shown is in the API reference below.\n\n### Functions\n\n```ts\n// Start a geometry assertion chain\nexport declare function expectGeo(subject: GeoSpecSubject, options?: GeoSpecExpectOptions): GeoSpecMatcher;\n\n// A model admitted by one live GeoSpec host scope\nGeoSpecSubject: {\n readonly [subjectBrand]: true\n}\n\n// Per-chain options accepted by `expectGeo(subject, options)`\nGeoSpecExpectOptions: {\n // Deterministic work-unit budget for every claim in this chain\n readonly workUnitLimit?: number\n}\n\n// Load a CAD model into GeoSpec evidence\nexport declare function loadModel<Code extends Record<string, string> = Record<string, string>>(_options: LoadModelOptions<Code>): Promise<GeoSpecSubject>;\n\n// Options accepted by {@link import ('./load-model.js').loadModel}\nLoadModelOptions: LoadModelSourceOptions | LoadModelCodeOptions<Code> | LoadModelFileOptions\n // Project-relative folder `file` resolves in, for a suite that loads from somewhere other than…\n rootDir?: string\n // Geometry format to export\n format?: GeoSpecModelFormat\n // Explicit parameters passed to the exporter\n parameters?: Record<string, unknown>\n // STEP reader strategy used for STEP exports\n stepStreaming?: StepStreamingMode\n // Whether STEP loading should also produce mesh evidence\n mesh?: boolean\n // Linear tolerance used while meshing exact BRep evidence\n meshLinearTolerance?: number\n // Angular tolerance in degrees used while meshing exact BRep evidence\n meshAngularToleranceDegrees?: number\n // Default work-unit budget for every claim on this subject\n workUnitLimit?: number\n\n// Geometry formats accepted by {@link import ('./load-model.js').loadModel}\nGeoSpecModelFormat: MeshFileFormat | 'step' | 'stp'\n\n// GeoSpec test helper used inside VM-executed test modules\nexport declare function it(name: string, function_: GeoSpecTestCallback): void;\n skip(name: string, function_?: GeoSpecTestCallback): void;\n\n// GeoSpec suite helper used inside VM-executed test modules\nexport declare function describe(name: string, function_: GeoSpecTestCallback): void;\n skip(name: string, function_?: GeoSpecTestCallback): void;\n\n// Alias for {@link it}\nexport declare function test(name: string, function_: GeoSpecTestCallback): void;\n skip(name: string, function_?: GeoSpecTestCallback): void;\n```\n\n### Types\n\n```ts\n// Assertion chain returned by `expectGeo(subject)`\nGeoSpecMatcher: {\n // Core-owned negation\n readonly not: Omit<GeoSpecMatcher, 'not'>\n // Assert the fixed rational plate contract\n toSatisfyRationalPlate(): GeoSpecAssertion;\n // Assert the fixed parallel-plane distance contract\n toSatisfyParallelPlaneDistance(): GeoSpecAssertion;\n // Assert axis-aligned bounds, size, or center for a loaded geometry subject\n toHaveBoundingBox(first: Vec3 | GeoSpecBoundingBoxExpectation, second?: Vec3): GeoSpecAssertion;\n // Assert how many spatially disjoint chunks the mesh contains\n toHaveConnectedComponents(expected: GeoSpecConnectedComponentsExpectation): GeoSpecAssertion;\n // Assert closed mesh edge incidence\n toBeWatertight(): GeoSpecAssertion;\n // Assert that separate assembly components do not occupy the same solid volume\n toHaveNoComponentInterference(expected?: GeoSpecComponentInterferenceExpectation): GeoSpecAssertion;\n // Assert that named assembly occurrences exist with expected counts and bounds\n toHaveAssemblyOccurrences(expected: GeoSpecAssemblyOccurrencesExpectation): GeoSpecAssertion;\n // Assert that selected entities satisfy declared spatial relationships\n toHaveSpatialRelationships(expected: GeoSpecSpatialRelationshipsExpectation): GeoSpecAssertion;\n // Assert rendered mesh evidence is internally trustworthy for downstream checks\n toHaveMeshIntegrity(expected: GeoSpecMeshIntegrityExpectation): GeoSpecAssertion;\n // Assert that the subject carries no diagnostics at the rejected severities\n toHaveNoDiagnostics(expected?: GeoSpecNoDiagnosticsExpectation): GeoSpecAssertion;\n // Assert total surface area, preferring exact BRep mass properties when available\n toHaveSurfaceArea(expected: GeoSpecSurfaceAreaExpectation): GeoSpecAssertion;\n // Assert enclosed volume, preferring exact BRep mass properties when available\n toHaveVolume(expected: GeoSpecVolumeExpectation): GeoSpecAssertion;\n // Assert mass derived from exact mass properties or volume times density\n toHaveMass(expected: GeoSpecMassExpectation): GeoSpecAssertion;\n // Assert the center of mass or mesh-derived centroid for a closed subject\n toHaveCenterOfMass(expected: GeoSpecCenterOfMassExpectation): GeoSpecAssertion;\n // Assert that exact BRep evidence reports a valid shape\n toBeValidBrep(expected?: GeoSpecValidBrepExpectation): GeoSpecAssertion;\n // Assert exact BRep topology counts\n toHaveTopologyCounts(expected: GeoSpecTopologyCountsExpectation): GeoSpecAssertion;\n // Assert the STEP unit evidence\n toHaveStepUnits(expected: GeoSpecStepUnitsExpectation): GeoSpecAssertion;\n // Assert STEP product-structure evidence\n toHaveProductStructure(expected: GeoSpecProductStructureExpectation): GeoSpecAssertion;\n // Assert that BRep evidence contains a planar face matching the requested constraints\n toHavePlanarFace(expected: GeoSpecPlanarFaceExpectation): GeoSpecAssertion;\n // Assert that BRep evidence contains a cylindrical face with the requested radius and axis\n toHaveCylindricalFace(expected: GeoSpecCylindricalFaceExpectation): GeoSpecAssertion;\n // Assert that BRep evidence contains a circular hole matching diameter, center, and axis\n toHaveCircularHole(expected: GeoSpecCircularHoleExpectation): GeoSpecAssertion;\n // Assert that BRep evidence contains a repeated circular-hole pattern\n toHaveCircularHolePattern(expected: GeoSpecCircularHolePatternExpectation): GeoSpecAssertion;\n // Assert that BRep evidence contains a chamfer feature with the requested distance\n toHaveChamferFeature(expected: GeoSpecChamferFeatureExpectation): GeoSpecAssertion;\n // Assert that BRep evidence contains a fillet feature with the requested radius\n toHaveFilletFeature(expected: GeoSpecFilletFeatureExpectation): GeoSpecAssertion;\n // Assert that BRep evidence reports a minimum wall thickness satisfying the expectation\n toHaveMinimumWallThickness(expected: GeoSpecMinimumWallThicknessExpectation): GeoSpecAssertion;\n // Assert that the declared waypoints share one connected void, stay isolated from the declared…\n toHaveVoidContinuity(expected: GeoSpecVoidContinuityExpectation): GeoSpecAssertion;\n}\n\n// Numeric 3D vector\nVec3: readonly [number, number, number]\n\n// Bounding-box expectation accepted by `expectGeo(...).toHaveBoundingBox(...)`\nGeoSpecBoundingBoxExpectation: {\n min?: Vec3 | Partial<Record<keyof GeoSpecAxisExpectation, GeoSpecNumericExpectation>>\n max?: Vec3 | Partial<Record<keyof GeoSpecAxisExpectation, GeoSpecNumericExpectation>>\n size?: Vec3 | Partial<Record<keyof GeoSpecAxisExpectation, GeoSpecNumericExpectation>>\n center?: Vec3 | Partial<Record<keyof GeoSpecAxisExpectation, GeoSpecNumericExpectation>>\n tolerance?: number\n}\n\n// Connected-components expectation accepted by `expectGeo(...).toHaveConnectedComponents(...)`\nGeoSpecConnectedComponentsExpectation: {\n count: number\n tolerance?: number\n toleranceMm?: number\n}\n\n// Component-interference expectation accepted by `expectGeo(...).toHaveNoComponentInterference(...)`\nGeoSpecComponentInterferenceExpectation: {\n tolerance?: number\n pairs?: GeoSpecComponentInterferencePairExpectation[]\n allowances?: GeoSpecComponentInterferenceAllowance[]\n}\n\n// Assembly occurrence expectation accepted by `expectGeo(...).toHaveAssemblyOccurrences(...)`\nGeoSpecAssemblyOccurrencesExpectation: {\n occurrences: GeoSpecAssemblyOccurrenceExpectation[]\n uniqueNames?: boolean\n}\n\n// Spatial relationship expectation accepted by `expectGeo(...).toHaveSpatialRelationships(...)`\nGeoSpecSpatialRelationshipsExpectation: {\n relationships: GeoSpecSpatialRelationshipExpectation[]\n}\n\n// Mesh integrity expectation accepted by `expectGeo(...).toHaveMeshIntegrity(...)`\nGeoSpecMeshIntegrityExpectation: {\n finitePositions?: boolean\n degenerateTriangles?: {\n count?: number;\n maxCount?: number;\n areaTolerance?: number;\n }\n duplicateFaces?: {\n count?: number;\n maxCount?: number;\n }\n watertight?: boolean\n triangleCount?: GeoSpecNumericExpectation\n}\n\n// Diagnostic severities rejected by `expectGeo(...).toHaveNoDiagnostics(...)`\nGeoSpecNoDiagnosticsExpectation: {\n severities?: Array<GeometryDiagnostic['severity']>\n}\n\n// Surface-area expectation accepted by `expectGeo(...).toHaveSurfaceArea(...)`\nGeoSpecSurfaceAreaExpectation: {\n value: number | GeoSpecNumericExpectation\n tolerance?: number\n}\n\n// Volume expectation accepted by `expectGeo(...).toHaveVolume(...)`\nGeoSpecVolumeExpectation: {\n value: number | GeoSpecNumericExpectation\n tolerance?: number\n}\n\n// Mass expectation accepted by `expectGeo(...).toHaveMass(...)`\nGeoSpecMassExpectation: {\n value: number | GeoSpecNumericExpectation\n density?: number\n tolerance?: number\n}\n\n// Center-of-mass expectation accepted by `expectGeo(...).toHaveCenterOfMass(...)`\nGeoSpecCenterOfMassExpectation: {\n // Exact expected point in millimetres\n point: GeoSpecPointExpectation\n tolerance?: number\n}\n\n// Exact BRep validity expectation accepted by `expectGeo(...).toBeValidBrep(...)`\nGeoSpecValidBrepExpectation: {\n maxTolerance?: number\n freeBounds?: {\n count?: GeoSpecNumericExpectation;\n }\n minEdgeLength?: number\n sameParameter?: boolean\n closedShells?: boolean\n closedWires?: boolean\n}\n\n// Topology-count expectation accepted by `expectGeo(...).toHaveTopologyCounts(...)`\nGeoSpecTopologyCountsExpectation: {\n vertices?: GeoSpecNumericExpectation\n edges?: GeoSpecNumericExpectation\n wires?: GeoSpecNumericExpectation\n faces?: GeoSpecNumericExpectation\n shells?: GeoSpecNumericExpectation\n solids?: GeoSpecNumericExpectation\n compounds?: GeoSpecNumericExpectation\n tolerance?: number\n}\n\n// STEP unit expectation accepted by `expectGeo(...).toHaveStepUnits(...)`\nGeoSpecStepUnitsExpectation: {\n unit: string\n}\n\n// Product-structure expectation accepted by `expectGeo(...).toHaveProductStructure(...)`\nGeoSpecProductStructureExpectation: {\n names?: string[]\n count?: GeoSpecNumericExpectation\n}\n\n// Planar-face expectation accepted by `expectGeo(...).toHavePlanarFace(...)`\nGeoSpecPlanarFaceExpectation: {\n normal: GeoSpecPointExpectation\n offset: number\n area?: GeoSpecNumericExpectation\n tolerance?: number\n}\n\n// Cylindrical-face expectation accepted by `expectGeo(...).toHaveCylindricalFace(...)`\nGeoSpecCylindricalFaceExpectation: {\n radius: number\n axis: 'x' | 'y' | 'z'\n tolerance?: number\n}\n\n// Circular-hole expectation accepted by `expectGeo(...).toHaveCircularHole(...)`\nGeoSpecCircularHoleExpectation: {\n diameter: number\n through?: boolean\n axis?: 'x' | 'y' | 'z'\n center?: GeoSpecPointExpectation\n tolerance?: number\n}\n\n// Circular-hole-pattern expectation accepted by `expectGeo(...).toHaveCircularHolePattern(...)`\nGeoSpecCircularHolePatternExpectation: {\n count: number\n holeDiameter: number\n boltCircleDiameter?: number\n axis?: 'x' | 'y' | 'z'\n center?: GeoSpecPointExpectation\n tolerance?: number\n}\n\n// Chamfer-feature expectation accepted by `expectGeo(...).toHaveChamferFeature(...)`\nGeoSpecChamferFeatureExpectation: {\n distance: number\n selection?: string\n tolerance?: number\n}\n\n// Fillet-feature expectation accepted by `expectGeo(...).toHaveFilletFeature(...)`\nGeoSpecFilletFeatureExpectation: {\n radius: number\n selection?: string\n tolerance?: number\n}\n\n// Minimum-wall-thickness expectation accepted by `expectGeo(...).toHaveMinimumWallThickness(...)`\nGeoSpecMinimumWallThicknessExpectation: {\n value: GeoSpecNumericExpectation\n tolerance?: number\n}\n\n// Void-continuity expectation accepted by `expectGeo(...).toHaveVoidContinuity(...)`\nGeoSpecVoidContinuityExpectation: {\n // Ordered waypoints (>= 1) known to lie in the void being proven\n path: GeoSpecVoidWaypoint[]\n // Occurrence names whose solids bound the void\n material?: string[]\n // Minimum required bottleneck cross-section (mm²), sampled\n minCrossSection?: number\n // Points that must NOT be reachable from the path void (isolation claim)\n isolatedFrom?: Vec3[]\n // Region bounded for the proof (subject frame)\n bounds?: {\n min: Vec3;\n max: Vec3;\n }\n}\n\n// Axis-keyed numeric expectation used by high-level geometry matchers\nGeoSpecAxisExpectation: {\n x?: number\n y?: number\n z?: number\n}\n\n// Shared scalar expectation used by geometry measurements\nGeoSpecNumericExpectation: number | {\n value?: number;\n greaterThan?: number;\n greaterThanOrEqual?: number;\n lessThan?: number;\n lessThanOrEqual?: number;\n}\n\n// A pair-specific component-interference check accepted by `expectGeo(...).toHaveNoComponentInterference(...)`\nGeoSpecComponentInterferencePairExpectation: {\n left: GeoSpecComponentSelector\n right: GeoSpecComponentSelector\n}\n\n// Intentional component interference allowance accepted by `expectGeo(...).toHaveNoComponentInterference(...)`\nGeoSpecComponentInterferenceAllowance: {\n kind?: 'intentionalInterference'\n left: GeoSpecComponentSelector\n right: GeoSpecComponentSelector\n maxVolume?: number\n reason: string\n}\n\n// Assembly occurrence rule accepted by `expectGeo(...).toHaveAssemblyOccurrences(...)`\nGeoSpecAssemblyOccurrenceExpectation: {\n name: GeoSpecComponentSelector\n count?: GeoSpecNumericExpectation\n bounds?: {\n within?: GeoSpecComponentSelector;\n min?: Vec3 | GeoSpecAxisExpectation;\n max?: Vec3 | GeoSpecAxisExpectation;\n center?: GeoSpecPointExpectation;\n tolerance?: number;\n }\n}\n\n// One spatial relationship accepted by `expectGeo(...).toHaveSpatialRelationships(...)`\nGeoSpecSpatialRelationshipExpectation: {\n id?: string\n kind: 'contact' | 'clearance' | 'coaxial' | 'concentric' | 'coplanar' | 'parallel' | 'perpendicular' | 'angle' | 'containment' | 'insertion' | 'interference'\n subject: GeoSpecGeometrySelector\n target: GeoSpecGeometrySelector\n tolerance?: number\n angularToleranceDegrees?: number\n // Expected angle in degrees for `kind\n angleDegrees?: number\n // Declared insertion axis (subject-frame direction) for `kind\n axis?: Vec3\n min?: number\n max?: number\n minVolume?: number\n maxVolume?: number\n reason?: string\n}\n\n// Diagnostic emitted by GeoSpec loaders, analyzers, and matchers\nGeometryDiagnostic: {\n code: KernelIssueCode | (string & {})\n severity: 'error' | 'warning' | 'info'\n message: string\n suggestion?: string\n spatial?: {\n min?: Vec3;\n max?: Vec3;\n center?: Vec3;\n }\n details?: unknown\n}\n\n// Point expectation accepted by center and feature matchers\nGeoSpecPointExpectation: Vec3 | GeoSpecAxisExpectation\n\n// One void-continuity waypoint\nGeoSpecVoidWaypoint: Vec3 | {\n occurrence: string;\n}\n\n// Direct geometry-source model load options\nLoadModelSourceOptions: {\n // Source geometry format\n format?: GeoSpecModelFormat\n // Explicit parameters recorded in provenance\n parameters?: Record<string, unknown>\n // Whether STEP loading should also produce mesh evidence\n mesh?: boolean\n // … 10 more members in the API reference: source, resources, rootDir, path, name, sourceUnit, stepStreaming, meshLinearTolerance, meshAngularToleranceDegrees, workUnitLimit\n}\n```\n\n## API reference\n\nTo 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.\n\n- `api-functions.md` — Functions\n- `api-constants.md` — Constants\n- `api-types.md` — Types\n- `api-classes.md` — Classes\n\nRead ranges, not whole files. Never copy a reference into a source file.\n"
26
+ "body": "---\nname: geospec-authoring\ndescription: Guides canonical GeoSpec geometry tests in TypeScript or JavaScript for every Tau kernel. Use for *.geospec.ts and *.geospec.js tests.\n---\n\n# GeoSpec authoring\n\nWrite tests before implementation; assert deterministic, measurable properties.\n\n## Test shape\n\n- Use `*.geospec.ts` or `*.geospec.js`. Import `describe`, `it` and `expectGeo` from `geospec`, and `loadModel` from `geospec/model`.\n- Await `loadModel`, then assert synchronously with `expectGeo(model)`. The host supplies the compiled binding; authoring does not select an engine.\n- Await or return the complete model-load chain from the test callback; detached future loads are not part of a completed test.\n- Omit `parameters` for model-code defaults; use `{ file, parameters }` for variants. Loaded subjects are opaque.\n- `loadModel({ file })` resolves `file` against the project root, the same root as every tool's `targetFile`; the result names that root as `projectRoot` where the host reports it, as `tau mcp` does. A suite in a subfolder names the model by its path from that root, or passes `rootDir`, the project-relative folder the model is in: `loadModel({ file: 'main.ts', rootDir: 'parts/gear' })` loads `parts/gear/main.ts`. A file the root does not hold refuses with `GEOSPEC_MODEL_SOURCE_NOT_FOUND`, which names the root and the path it looked for.\n\nCanonical TypeScript authoring:\n\n```ts\nimport { describe, expectGeo, it } from 'geospec';\nimport { loadModel } from 'geospec/model';\n\ndescribe('main geometry', () => {\n it('has the intended envelope', async () => {\n const model = await loadModel({ file: 'main.ts', parameters: { width: 120 } });\n expectGeo(model).toHaveBoundingBox({ size: { x: 120 }, tolerance: 1 });\n });\n});\n```\n\nSpecs are always TypeScript or JavaScript, whatever the model's kernel: `loadModel({ file })` evaluates `main.ts`, `main.tsx`, `main.py`, `main.scad`, `main.kcl` or `main.cs` through Tau's runtime. `test_model` discovers `*.geospec.ts` and `*.geospec.js` only.\n\nEvery matcher takes one expectation object:\n\n- Wrong: `expectGeo(model).toHaveVolume(5000, { tolerance: 5 })`. Correct: `expectGeo(model).toHaveVolume({ value: 5000, tolerance: 5 })`.\n- Wrong: `await expectGeo(model)…`. Correct: await `loadModel`, then assert synchronously.\n- Wrong: exact-feature matchers on a mesh kernel (Manifold, JSCAD, OpenSCAD, PicoGK, PicoVoxel). Correct: `toBeValidBrep`, `toHaveTopologyCounts`, the face, hole, pattern, chamfer, fillet and wall-thickness matchers, `toHaveStepUnits`, `toHaveProductStructure` and `toHaveVoidContinuity` need STEP BRep evidence and report unsupported on meshes; assert meshes with bounds, volume, surface area, connected components and `toBeWatertight`.\n\n## Loads and budgets\n\n- GeoSpec has no `beforeAll`. Write each `loadModel` inside its own `it`: within one run, identical loads (same file or code, parameters, format, tolerances and region) share one export and one admission. Each load keeps its own `loadId` and records `reused: true`, and a file is reused only while its source closure is unchanged.\n- `loadModel({ file, workUnitLimit })` sets the default claim budget for that subject, and `expectGeo(model, { workUnitLimit })` overrides it for one chain. The budget is a positive integer no greater than 512000000. A `MATCHER_TIMEOUT` refusal reports `details.limit` and, when measured, `details.used`; its `test_model` row (category `work-budget`) names in `limit.retry` the one `workUnitLimit` that can decide the claim, or `null` at the host maximum. Never treat the refusal as a pass.\n- `loadModel({ file, region: { min: [x, y, z], max: [x, y, z] } })` makes a separate claim about one millimetre box, never a stand-in for a whole-model claim. The kernel crops before export (PicoVoxel trims Voxels parts), and other kernels, STEP loads and unconfirmed crops refuse with a typed diagnostic. A cropped subject answers only bounding box, volume, surface area, mass and center of mass of its region, and its assertions record the region. Every other matcher on it refuses with `GEOSPEC_REGION_WHOLE_MODEL_CLAIM`. Name the region in the test, and keep whole-model claims on whole-model loads.\n- A host or engine limit leaves a claim undecided, never false: `test_model` reports it as inconclusive with category `analysis-limit`, `resource-limit` or `work-budget` and a typed `limit` naming the limit and its numbers. Keep the model as designed: never coarsen, shrink or crop it to fit. Only a `work-budget` row's `limit.retry` is a retry, and `testTimeout` only answers a `timeout` row; report every other limit row as not decided at this capacity.\n- `toHaveCenterOfMass({ point, tolerance })` takes an exact point. Per-axis ranges such as `{ y: { greaterThan: 1 } }` are refused.\n\n## Ceilings\n\nFixed in this release; design within them, and report a claim that meets one as not decided.\n\n| Ceiling | Value | Where an agent meets it |\n| ------------------------------------- | -------------------- | --------------------------------------------------------------------------------------------------------------------------------- |\n| `maxSubjectBytes`, `maxResourceBytes` | 64 MiB each | A mesh `loadModel({ file })` exports about 72 bytes per triangle, so admission refuses near 930,000 triangles (`resource-limit`). |\n| `maxTotalBinaryBytes` | 128 MiB | All subjects of one load together. |\n| `maxTriangles`, `maxVertices` | 4,000,000, 2,000,000 | A decoded mesh. |\n| `continuousEvidenceBytes` | 32 MiB | `toHaveNoComponentInterference` on a large assembly (`analysis-limit`). |\n| `workUnitLimit` | 512000000 at most | Any claim; the only limit an argument raises. |\n\nLoad `format: 'step'` only for the exact-BRep matchers above; every other matcher answers on the cheaper mesh.\n\n## Coverage\n\nBounds and physical properties are insufficient. Cover major components, named features, variants, dimensions/positions, disjoint counts, closure, interference and supported exact features. Explicitly report unsupported requirements; proxies cannot fulfill them.\n\n- `toHaveBoundingBox`: size/position.\n- `toHaveConnectedComponents`: qualified material connectivity; visual touching cannot justify tolerance changes.\n- `toBeWatertight`: closed edge incidence, not manifold validity, fusion or material connectivity. Bounds prove none of these. Missing evidence is unsupported.\n- `toHaveSurfaceArea`, `toHaveVolume`, `toHaveCenterOfMass`, `toHaveMass`: physical measurements.\n- `toHaveNoComponentInterference`: overlap; allow deliberate press fits.\n- `loadModel({ file, format: 'step' })`: use BRep evidence for supported topology and feature assertions. Missing occurrence, interference, clearance, containment, lumen, wall, section or motion evidence is unsupported, not a pass or an envelope substitute.\n\nTest assemblies and independent units; preserve sibling coverage when adding files. Non-top-level geometry needs kernel export/invocation, not test removal.\n\nFix geometry at its root; never weaken tolerances, delete assertions, or reduce detail to pass.\n\n`public-api-index.md` covers the host and framework API; authoring needs only the Core API below and `api-*` files.\n\n## Core API\n\nThe symbols real Tau models use most, as verbatim declarations. Anything not shown is in the API reference below.\n\n### Functions\n\n```ts\n// Start a geometry assertion chain\nexport declare function expectGeo(subject: GeoSpecSubject, options?: GeoSpecExpectOptions): GeoSpecMatcher;\n\n// A model admitted by one live GeoSpec host scope\nGeoSpecSubject: {\n readonly [subjectBrand]: true\n}\n\n// Per-chain options accepted by `expectGeo(subject, options)`\nGeoSpecExpectOptions: {\n // Deterministic work-unit budget for every claim in this chain\n readonly workUnitLimit?: number\n}\n\n// Load a CAD model into GeoSpec evidence\nexport declare function loadModel<Code extends Record<string, string> = Record<string, string>>(_options: LoadModelOptions<Code>): Promise<GeoSpecSubject>;\n\n// Options accepted by {@link import ('./load-model.js').loadModel}\nLoadModelOptions: LoadModelSourceOptions | LoadModelCodeOptions<Code> | LoadModelFileOptions\n // Project-relative folder `file` resolves in, for a suite that loads from somewhere other than…\n rootDir?: string\n // Geometry format to export\n format?: GeoSpecModelFormat\n // Explicit parameters passed to the exporter\n parameters?: Record<string, unknown>\n // STEP reader strategy used for STEP exports\n stepStreaming?: StepStreamingMode\n // Whether STEP loading should also produce mesh evidence\n mesh?: boolean\n // Linear tolerance used while meshing exact BRep evidence\n meshLinearTolerance?: number\n // Angular tolerance in degrees used while meshing exact BRep evidence\n meshAngularToleranceDegrees?: number\n // Default work-unit budget for every claim on this subject\n workUnitLimit?: number\n\n// Geometry formats accepted by {@link import ('./load-model.js').loadModel}\nGeoSpecModelFormat: MeshFileFormat | 'step' | 'stp'\n\n// GeoSpec test helper used inside VM-executed test modules\nexport declare function it(name: string, function_: GeoSpecTestCallback): void;\n skip(name: string, function_?: GeoSpecTestCallback): void;\n\n// GeoSpec suite helper used inside VM-executed test modules\nexport declare function describe(name: string, function_: GeoSpecTestCallback): void;\n skip(name: string, function_?: GeoSpecTestCallback): void;\n\n// Alias for {@link it}\nexport declare function test(name: string, function_: GeoSpecTestCallback): void;\n skip(name: string, function_?: GeoSpecTestCallback): void;\n```\n\n### Types\n\n```ts\n// Assertion chain returned by `expectGeo(subject)`\nGeoSpecMatcher: {\n // Core-owned negation\n readonly not: Omit<GeoSpecMatcher, 'not'>\n // Assert the fixed rational plate contract\n toSatisfyRationalPlate(): GeoSpecAssertion;\n // Assert the fixed parallel-plane distance contract\n toSatisfyParallelPlaneDistance(): GeoSpecAssertion;\n // Assert axis-aligned bounds, size, or center for a loaded geometry subject\n toHaveBoundingBox(first: Vec3 | GeoSpecBoundingBoxExpectation, second?: Vec3): GeoSpecAssertion;\n // Assert how many spatially disjoint chunks the mesh contains\n toHaveConnectedComponents(expected: GeoSpecConnectedComponentsExpectation): GeoSpecAssertion;\n // Assert closed mesh edge incidence\n toBeWatertight(): GeoSpecAssertion;\n // Assert that separate assembly components do not occupy the same solid volume\n toHaveNoComponentInterference(expected?: GeoSpecComponentInterferenceExpectation): GeoSpecAssertion;\n // Assert that named assembly occurrences exist with expected counts and bounds\n toHaveAssemblyOccurrences(expected: GeoSpecAssemblyOccurrencesExpectation): GeoSpecAssertion;\n // Assert that selected entities satisfy declared spatial relationships\n toHaveSpatialRelationships(expected: GeoSpecSpatialRelationshipsExpectation): GeoSpecAssertion;\n // Assert rendered mesh evidence is internally trustworthy for downstream checks\n toHaveMeshIntegrity(expected: GeoSpecMeshIntegrityExpectation): GeoSpecAssertion;\n // Assert that the subject carries no diagnostics at the rejected severities\n toHaveNoDiagnostics(expected?: GeoSpecNoDiagnosticsExpectation): GeoSpecAssertion;\n // Assert total surface area, preferring exact BRep mass properties when available\n toHaveSurfaceArea(expected: GeoSpecSurfaceAreaExpectation): GeoSpecAssertion;\n // Assert enclosed volume, preferring exact BRep mass properties when available\n toHaveVolume(expected: GeoSpecVolumeExpectation): GeoSpecAssertion;\n // Assert mass derived from exact mass properties or volume times density\n toHaveMass(expected: GeoSpecMassExpectation): GeoSpecAssertion;\n // Assert the center of mass or mesh-derived centroid for a closed subject\n toHaveCenterOfMass(expected: GeoSpecCenterOfMassExpectation): GeoSpecAssertion;\n // Assert that exact BRep evidence reports a valid shape\n toBeValidBrep(expected?: GeoSpecValidBrepExpectation): GeoSpecAssertion;\n // Assert exact BRep topology counts\n toHaveTopologyCounts(expected: GeoSpecTopologyCountsExpectation): GeoSpecAssertion;\n // Assert the STEP unit evidence\n toHaveStepUnits(expected: GeoSpecStepUnitsExpectation): GeoSpecAssertion;\n // Assert STEP product-structure evidence\n toHaveProductStructure(expected: GeoSpecProductStructureExpectation): GeoSpecAssertion;\n // Assert that BRep evidence contains a planar face matching the requested constraints\n toHavePlanarFace(expected: GeoSpecPlanarFaceExpectation): GeoSpecAssertion;\n // Assert that BRep evidence contains a cylindrical face with the requested radius and axis\n toHaveCylindricalFace(expected: GeoSpecCylindricalFaceExpectation): GeoSpecAssertion;\n // Assert that BRep evidence contains a circular hole matching diameter, center, and axis\n toHaveCircularHole(expected: GeoSpecCircularHoleExpectation): GeoSpecAssertion;\n // Assert that BRep evidence contains a repeated circular-hole pattern\n toHaveCircularHolePattern(expected: GeoSpecCircularHolePatternExpectation): GeoSpecAssertion;\n // Assert that BRep evidence contains a chamfer feature with the requested distance\n toHaveChamferFeature(expected: GeoSpecChamferFeatureExpectation): GeoSpecAssertion;\n // Assert that BRep evidence contains a fillet feature with the requested radius\n toHaveFilletFeature(expected: GeoSpecFilletFeatureExpectation): GeoSpecAssertion;\n // Assert that BRep evidence reports a minimum wall thickness satisfying the expectation\n toHaveMinimumWallThickness(expected: GeoSpecMinimumWallThicknessExpectation): GeoSpecAssertion;\n // Assert that the declared waypoints share one connected void, stay isolated from the declared…\n toHaveVoidContinuity(expected: GeoSpecVoidContinuityExpectation): GeoSpecAssertion;\n}\n\n// Numeric 3D vector\nVec3: readonly [number, number, number]\n\n// Bounding-box expectation accepted by `expectGeo(...).toHaveBoundingBox(...)`\nGeoSpecBoundingBoxExpectation: {\n min?: Vec3 | Partial<Record<keyof GeoSpecAxisExpectation, GeoSpecNumericExpectation>>\n max?: Vec3 | Partial<Record<keyof GeoSpecAxisExpectation, GeoSpecNumericExpectation>>\n size?: Vec3 | Partial<Record<keyof GeoSpecAxisExpectation, GeoSpecNumericExpectation>>\n center?: Vec3 | Partial<Record<keyof GeoSpecAxisExpectation, GeoSpecNumericExpectation>>\n tolerance?: number\n}\n\n// Connected-components expectation accepted by `expectGeo(...).toHaveConnectedComponents(...)`\nGeoSpecConnectedComponentsExpectation: {\n count: number\n tolerance?: number\n toleranceMm?: number\n}\n\n// Component-interference expectation accepted by `expectGeo(...).toHaveNoComponentInterference(...)`\nGeoSpecComponentInterferenceExpectation: {\n tolerance?: number\n pairs?: GeoSpecComponentInterferencePairExpectation[]\n allowances?: GeoSpecComponentInterferenceAllowance[]\n}\n\n// Assembly occurrence expectation accepted by `expectGeo(...).toHaveAssemblyOccurrences(...)`\nGeoSpecAssemblyOccurrencesExpectation: {\n occurrences: GeoSpecAssemblyOccurrenceExpectation[]\n uniqueNames?: boolean\n}\n\n// Spatial relationship expectation accepted by `expectGeo(...).toHaveSpatialRelationships(...)`\nGeoSpecSpatialRelationshipsExpectation: {\n relationships: GeoSpecSpatialRelationshipExpectation[]\n}\n\n// Mesh integrity expectation accepted by `expectGeo(...).toHaveMeshIntegrity(...)`\nGeoSpecMeshIntegrityExpectation: {\n finitePositions?: boolean\n degenerateTriangles?: {\n count?: number;\n maxCount?: number;\n areaTolerance?: number;\n }\n duplicateFaces?: {\n count?: number;\n maxCount?: number;\n }\n watertight?: boolean\n triangleCount?: GeoSpecNumericExpectation\n}\n\n// Diagnostic severities rejected by `expectGeo(...).toHaveNoDiagnostics(...)`\nGeoSpecNoDiagnosticsExpectation: {\n severities?: Array<GeometryDiagnostic['severity']>\n}\n\n// Surface-area expectation accepted by `expectGeo(...).toHaveSurfaceArea(...)`\nGeoSpecSurfaceAreaExpectation: {\n value: number | GeoSpecNumericExpectation\n tolerance?: number\n}\n\n// Volume expectation accepted by `expectGeo(...).toHaveVolume(...)`\nGeoSpecVolumeExpectation: {\n value: number | GeoSpecNumericExpectation\n tolerance?: number\n}\n\n// Mass expectation accepted by `expectGeo(...).toHaveMass(...)`\nGeoSpecMassExpectation: {\n value: number | GeoSpecNumericExpectation\n density?: number\n tolerance?: number\n}\n\n// Center-of-mass expectation accepted by `expectGeo(...).toHaveCenterOfMass(...)`\nGeoSpecCenterOfMassExpectation: {\n // Exact expected point in millimetres\n point: GeoSpecPointExpectation\n tolerance?: number\n}\n\n// Exact BRep validity expectation accepted by `expectGeo(...).toBeValidBrep(...)`\nGeoSpecValidBrepExpectation: {\n maxTolerance?: number\n freeBounds?: {\n count?: GeoSpecNumericExpectation;\n }\n minEdgeLength?: number\n sameParameter?: boolean\n closedShells?: boolean\n closedWires?: boolean\n}\n\n// Topology-count expectation accepted by `expectGeo(...).toHaveTopologyCounts(...)`\nGeoSpecTopologyCountsExpectation: {\n vertices?: GeoSpecNumericExpectation\n edges?: GeoSpecNumericExpectation\n wires?: GeoSpecNumericExpectation\n faces?: GeoSpecNumericExpectation\n shells?: GeoSpecNumericExpectation\n solids?: GeoSpecNumericExpectation\n compounds?: GeoSpecNumericExpectation\n tolerance?: number\n}\n\n// STEP unit expectation accepted by `expectGeo(...).toHaveStepUnits(...)`\nGeoSpecStepUnitsExpectation: {\n unit: string\n}\n\n// Product-structure expectation accepted by `expectGeo(...).toHaveProductStructure(...)`\nGeoSpecProductStructureExpectation: {\n names?: string[]\n count?: GeoSpecNumericExpectation\n}\n\n// Planar-face expectation accepted by `expectGeo(...).toHavePlanarFace(...)`\nGeoSpecPlanarFaceExpectation: {\n normal: GeoSpecPointExpectation\n offset: number\n area?: GeoSpecNumericExpectation\n tolerance?: number\n}\n\n// Cylindrical-face expectation accepted by `expectGeo(...).toHaveCylindricalFace(...)`\nGeoSpecCylindricalFaceExpectation: {\n radius: number\n axis: 'x' | 'y' | 'z'\n tolerance?: number\n}\n\n// Circular-hole expectation accepted by `expectGeo(...).toHaveCircularHole(...)`\nGeoSpecCircularHoleExpectation: {\n diameter: number\n through?: boolean\n axis?: 'x' | 'y' | 'z'\n center?: GeoSpecPointExpectation\n tolerance?: number\n}\n\n// Circular-hole-pattern expectation accepted by `expectGeo(...).toHaveCircularHolePattern(...)`\nGeoSpecCircularHolePatternExpectation: {\n count: number\n holeDiameter: number\n boltCircleDiameter?: number\n axis?: 'x' | 'y' | 'z'\n center?: GeoSpecPointExpectation\n tolerance?: number\n}\n\n// Chamfer-feature expectation accepted by `expectGeo(...).toHaveChamferFeature(...)`\nGeoSpecChamferFeatureExpectation: {\n distance: number\n selection?: string\n tolerance?: number\n}\n\n// Fillet-feature expectation accepted by `expectGeo(...).toHaveFilletFeature(...)`\nGeoSpecFilletFeatureExpectation: {\n radius: number\n selection?: string\n tolerance?: number\n}\n\n// Minimum-wall-thickness expectation accepted by `expectGeo(...).toHaveMinimumWallThickness(...)`\nGeoSpecMinimumWallThicknessExpectation: {\n value: GeoSpecNumericExpectation\n tolerance?: number\n}\n\n// Void-continuity expectation accepted by `expectGeo(...).toHaveVoidContinuity(...)`\nGeoSpecVoidContinuityExpectation: {\n // Ordered waypoints (>= 1) known to lie in the void being proven\n path: GeoSpecVoidWaypoint[]\n // Occurrence names whose solids bound the void\n material?: string[]\n // Minimum required bottleneck cross-section (mm²), sampled\n minCrossSection?: number\n // Points that must NOT be reachable from the path void (isolation claim)\n isolatedFrom?: Vec3[]\n // Region bounded for the proof (subject frame)\n bounds?: {\n min: Vec3;\n max: Vec3;\n }\n}\n\n// Axis-keyed numeric expectation used by high-level geometry matchers\nGeoSpecAxisExpectation: {\n x?: number\n y?: number\n z?: number\n}\n\n// Shared scalar expectation used by geometry measurements\nGeoSpecNumericExpectation: number | {\n value?: number;\n greaterThan?: number;\n greaterThanOrEqual?: number;\n lessThan?: number;\n lessThanOrEqual?: number;\n}\n\n// A pair-specific component-interference check accepted by `expectGeo(...).toHaveNoComponentInterference(...)`\nGeoSpecComponentInterferencePairExpectation: {\n left: GeoSpecComponentSelector\n right: GeoSpecComponentSelector\n}\n\n// Intentional component interference allowance accepted by `expectGeo(...).toHaveNoComponentInterference(...)`\nGeoSpecComponentInterferenceAllowance: {\n kind?: 'intentionalInterference'\n left: GeoSpecComponentSelector\n right: GeoSpecComponentSelector\n maxVolume?: number\n reason: string\n}\n\n// Assembly occurrence rule accepted by `expectGeo(...).toHaveAssemblyOccurrences(...)`\nGeoSpecAssemblyOccurrenceExpectation: {\n name: GeoSpecComponentSelector\n count?: GeoSpecNumericExpectation\n bounds?: {\n within?: GeoSpecComponentSelector;\n min?: Vec3 | GeoSpecAxisExpectation;\n max?: Vec3 | GeoSpecAxisExpectation;\n center?: GeoSpecPointExpectation;\n tolerance?: number;\n }\n}\n\n// One spatial relationship accepted by `expectGeo(...).toHaveSpatialRelationships(...)`\nGeoSpecSpatialRelationshipExpectation: {\n id?: string\n kind: 'contact' | 'clearance' | 'coaxial' | 'concentric' | 'coplanar' | 'parallel' | 'perpendicular' | 'angle' | 'containment' | 'insertion' | 'interference'\n subject: GeoSpecGeometrySelector\n target: GeoSpecGeometrySelector\n tolerance?: number\n angularToleranceDegrees?: number\n // Expected angle in degrees for `kind\n angleDegrees?: number\n // Declared insertion axis (subject-frame direction) for `kind\n axis?: Vec3\n min?: number\n max?: number\n minVolume?: number\n maxVolume?: number\n reason?: string\n}\n\n// Diagnostic emitted by GeoSpec loaders, analyzers, and matchers\nGeometryDiagnostic: {\n code: KernelIssueCode | (string & {})\n severity: 'error' | 'warning' | 'info'\n message: string\n suggestion?: string\n spatial?: {\n min?: Vec3;\n max?: Vec3;\n center?: Vec3;\n }\n details?: unknown\n}\n\n// Point expectation accepted by center and feature matchers\nGeoSpecPointExpectation: Vec3 | GeoSpecAxisExpectation\n\n// One void-continuity waypoint\nGeoSpecVoidWaypoint: Vec3 | {\n occurrence: string;\n}\n\n// Direct geometry-source model load options\nLoadModelSourceOptions: {\n // Source geometry format\n format?: GeoSpecModelFormat\n // Explicit parameters recorded in provenance\n parameters?: Record<string, unknown>\n // Whether STEP loading should also produce mesh evidence\n mesh?: boolean\n // … 10 more members in the API reference: source, resources, rootDir, path, name, sourceUnit, stepStreaming, meshLinearTolerance, meshAngularToleranceDegrees, workUnitLimit\n}\n```\n\n## API reference\n\nTo 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.\n\n- `api-functions.md` — Functions\n- `api-constants.md` — Constants\n- `api-types.md` — Types\n- `api-types-2.md` — Types (2)\n- `api-classes.md` — Classes\n\nRead ranges, not whole files. Never copy a reference into a source file.\n"
26
27
  }
27
28
  ]
28
29
  }
@@ -75,7 +75,9 @@ type MinimumDistanceResult = {
75
75
  * selectors are serialized by the shared protocol serializer.
76
76
  *
77
77
  * An explicit claimId leaves the automatic sequence unchanged. Queries return
78
- * full reports, including failed/refused reports, without assertion errors.
78
+ * full reports without assertion errors. A query asserts nothing, so it never
79
+ * fails: one whose evidence is missing or cannot decide returns a refused
80
+ * report whose diagnostic names the reason, such as `GEOSPEC_UNSUPPORTED_EVIDENCE`.
79
81
  * @public
80
82
  */
81
83
  type GeoSpecQueryOptions = {
@@ -0,0 +1,48 @@
1
+ import "../runner/types.mjs";
2
+ import { GeoSpecConfigData } from "../config/types.mjs";
3
+ import { discoverGeoSpecFiles } from "../runner/discovery.mjs";
4
+ import { GeoSpecRunner } from "../runner/worker/runner-types.mjs";
5
+ //#region src/cli/cli.d.ts
6
+ /**
7
+ * The platform the CLI runs against. Injected so the whole command — argument
8
+ * parsing, discovery, execution, reporting, exit code — is testable without a
9
+ * process.
10
+ *
11
+ * @public
12
+ */
13
+ type GeoSpecCliHost = {
14
+ /** Absolute project root for a relative `projectPath`. */
15
+ cwd(): string;
16
+ write(line: string): void;
17
+ /** Recursive discovery filesystem. */
18
+ discoveryFileSystem(projectPath: string): Parameters<typeof discoverGeoSpecFiles>[0]['filesystem'];
19
+ /**
20
+ * Import the project's `geospec.config.*`, or the explicit one, for its data fields.
21
+ * @throws Error when the config is ambiguous, invalid or fails to import.
22
+ */
23
+ loadConfig(options: {
24
+ projectPath: string;
25
+ configPath: string | undefined;
26
+ }): Promise<{
27
+ readonly configPath?: string;
28
+ readonly options: GeoSpecConfigData;
29
+ }>;
30
+ /** Build the runner the selected files execute on; its workers import the same config for its exporters. */
31
+ createRunner(options: {
32
+ projectPath: string;
33
+ configPath: string | undefined;
34
+ workers: number | undefined;
35
+ shardTimeout: number | undefined;
36
+ }): GeoSpecRunner;
37
+ };
38
+ /**
39
+ * Run the CLI.
40
+ *
41
+ * @param argv - Arguments after the executable and script.
42
+ * @param host - The injected platform.
43
+ * @returns The process exit code.
44
+ * @public
45
+ */
46
+ declare const runGeoSpecCli: (argv: readonly string[], host: GeoSpecCliHost) => Promise<number>;
47
+ //#endregion
48
+ export { GeoSpecCliHost, runGeoSpecCli };
@@ -0,0 +1,30 @@
1
+ import{protocolWireValue as e}from"./wire-value.mjs";import{discoverGeoSpecFiles as t}from"../runner/discovery.mjs";const n=`geospec — CAD geometry specs
2
+
3
+ Usage:
4
+ geospec run [projectPath] [options]
5
+
6
+ Options:
7
+ --file <path> GeoSpec file or directory root (repeatable)
8
+ --include <glob> Include glob (repeatable, default **/*.geospec.{ts,js})
9
+ --exclude <glob> Exclude glob (repeatable)
10
+ -t, --test-name-pattern <re> JavaScript regex matched against 'suite > test'
11
+ --test-timeout <ms> Per-test async timeout (GEOSPEC_TEST_TIMEOUT)
12
+ --workers [n] Run in a worker pool; omit n to auto-size
13
+ --shard-timeout <ms> Non-verdict per-shard watchdog (GEOSPEC_SHARD_TIMEOUT)
14
+ --bail Stop after the first failing file
15
+ --config <path> geospec.config.* to use (default: the one in projectPath)
16
+ --json Print one JSON result document and nothing else
17
+ -h, --help Show this help
18
+
19
+ Timeouts:
20
+ Every host reports wall-clock timeouts with one code family. None of them is
21
+ a geometry verdict, and nothing is timed out unless asked.
22
+ GEOSPEC_TEST_TIMEOUT a test outlived --test-timeout (test_model testTimeout);
23
+ the test still settles before the run moves on
24
+ GEOSPEC_SHARD_TIMEOUT a pool shard outlived --shard-timeout; its worker is
25
+ terminated
26
+ GEOSPEC_RUN_TIMEOUT a browser run outlived its host run budget; completed
27
+ requirements are still reported
28
+ The engine's work-unit budget (MATCHER_TIMEOUT) is deterministic, not a clock.
29
+ `,r=(e,t)=>{let n=Number(e);return e!==void 0&&Number.isFinite(n)&&n>=0?n:{error:`${t} needs a number.`}},i=e=>{if(e.length===0||e[0]===`-h`||e[0]===`--help`)return{kind:`help`,message:n};if(e[0]!==`run`)return{kind:`error`,message:`Unknown command '${e[0]}'.`};let t={projectPath:`.`,files:[],include:[],exclude:[],bail:!1,json:!1},i=!1;for(let a=1;a<e.length;a++){let o=e[a],s=e[a+1];switch(o){case`-h`:case`--help`:return{kind:`help`,message:n};case`--file`:if(s===void 0)return{kind:`error`,message:`--file needs a path.`};t.files.push(s),a+=1;continue;case`--config`:if(s===void 0)return{kind:`error`,message:`--config needs a path.`};t.config=s,a+=1;continue;case`--include`:case`--exclude`:if(s===void 0)return{kind:`error`,message:`${o} needs a glob.`};(o===`--include`?t.include:t.exclude).push(s),a+=1;continue;case`-t`:case`--test-name-pattern`:if(s===void 0)return{kind:`error`,message:`${o} needs a pattern.`};t.testNamePattern=s,a+=1;continue;case`--test-timeout`:case`--shard-timeout`:{let e=r(s,o);if(typeof e!=`number`)return{kind:`error`,message:e.error};o===`--test-timeout`?t.testTimeout=e:t.shardTimeout=e,a+=1;continue}case`--workers`:{if(s===void 0||s.startsWith(`-`)){t.workers=0;continue}let e=r(s,o);if(typeof e!=`number`)return{kind:`error`,message:e.error};t.workers=e,a+=1;continue}case`--bail`:t.bail=!0;continue;case`--json`:t.json=!0;continue;default:if(o.startsWith(`-`))return{kind:`error`,message:`Unknown option '${o}'.`};if(i)return{kind:`error`,message:`Unexpected argument '${o}'.`};t.projectPath=o,i=!0}}return{kind:`run`,options:t}},a=e=>[...e.suite,e.name].join(` > `),o={passed:`pass`,failed:`fail`,inconclusive:`inconclusive`,unsupported:`unsupported`,"not-run":`not-run`,skipped:`skip`},s=(e,t)=>{if(!t.success)return[`FAIL ${e}`,...t.issues.map(e=>` ${e.code}: ${e.message}`)];let n=[`${t.passed?`PASS`:`FAIL`} ${e}`];for(let e of t.tests){if(e.status===`passed`)continue;n.push(` ${o[e.status]} ${a(e)}`);let t=new Set;for(let r of[...e.diagnostics,...e.assertions.flatMap(e=>e.diagnostics??[])]){let e=` ${r.code}: ${r.message}`;t.has(e)||(t.add(e),n.push(e))}}return n},c=e=>{let t=[];for(let n of e.files)t.push(...s(n.file,n.result));for(let n of e.issues??[])t.push(`${n.code}: ${n.message}`);return t.push(l(e)),t},l=e=>{let{accounting:t}=e,n={passed:t?.passed??e.passed,failed:t?.failed??e.failed,inconclusive:t?.inconclusive??0,unsupported:t?.unsupported??0,notRun:t?.notRun??0,skipped:t?.skipped??0,total:t?.selected??e.selectedTests},r=n.failed>0?`failed`:n.inconclusive>0||t?.cancelled===!0?`inconclusive`:n.unsupported>0?`unsupported`:n.total===n.skipped?`not-run`:e.success?`passed`:`inconclusive`,i=[`${String(n.passed)} passed`,`${String(n.failed)} failed`];for(let[e,t]of[[n.inconclusive,`inconclusive`],[n.unsupported,`unsupported`],[n.notRun,`not run`],[n.skipped,`skipped`]])e>0&&i.push(`${String(e)} ${t}`);return`GeoSpec ${r}: ${i.join(`, `)} of ${String(n.total)}.`},u=t=>({success:t.success,passed:t.passed,failed:t.failed,selectedTests:t.selectedTests,...t.accounting===void 0?{}:{accounting:t.accounting},...t.lineageStatus===void 0?{}:{lineageStatus:t.lineageStatus},...t.durationMs===void 0?{}:{durationMs:t.durationMs},...t.issues===void 0?{}:{issues:t.issues},files:t.files.map(t=>({file:t.file,success:t.result.success&&t.result.passed,...t.result.accounting===void 0?{}:{accounting:t.result.accounting},...t.result.lineage===void 0?{}:{lineage:e(t.result.lineage)},...t.durationMs===void 0?{}:{durationMs:t.durationMs},...t.result.tests===void 0?{}:{tests:t.result.tests.map(e=>({suite:e.suite,name:e.name,...e.ordinal===void 0?{}:{ordinal:e.ordinal},status:e.status,...e.durationMs===void 0?{}:{durationMs:e.durationMs},diagnostics:[...e.diagnostics,...e.assertions.flatMap(e=>e.diagnostics??[])],...e.assertions.some(e=>e.report!==void 0)?{reports:e.assertions.flatMap(e=>{let{report:t}=e;return t===void 0?[]:[{claimId:t.claimId,status:t.status,polarity:t.polarity,claim:structuredClone(t.claim),result:structuredClone(t.result),diagnostics:structuredClone(t.diagnostics),...t.evidence===void 0?{}:{evidence:structuredClone(t.evidence)},...e.loadId===void 0?{}:{loadId:e.loadId},canonical:{claim:[...t.canonicalClaim],plan:[...t.canonicalPlan],result:[...t.canonicalResult]}}]})}:{}}))},...t.result.success?{}:{issues:t.result.issues}}))}),d=e=>{try{return JSON.stringify(e)}catch{return}};function*f(e,t=67108864){let n=d(e);if(n!==void 0&&n.length<=t){yield n;return}if(typeof e!=`object`||!e){yield n??`null`;return}if(Array.isArray(e)){yield`[`;for(let[n,r]of e.entries())n>0&&(yield`,`),yield*f(r,t);yield`]`;return}let r=Object.entries(e).filter(([,e])=>e!==void 0&&typeof e!=`function`&&typeof e!=`symbol`);yield`{`;for(let[e,[n,i]]of r.entries())yield`${e>0?`,`:``}${JSON.stringify(n)}:`,yield*f(i,t);yield`}`}const p=async(e,r)=>{let a=i(e);if(a.kind===`help`)return r.write(a.message),0;if(a.kind===`error`)return r.write(`${a.message}\n\n${n}`),1;let{options:o}=a,s=o.projectPath.startsWith(`/`)?o.projectPath:`${r.cwd()}/${o.projectPath}`.replace(/\/\.$/u,``),l;try{l=await r.loadConfig({projectPath:s,configPath:o.config})}catch(e){let t=`GeoSpec config: ${e instanceof Error?e.message:String(e)}`;return r.write(o.json?JSON.stringify({success:!1,error:t}):t),1}let d=o.include.length>0?o.include:l.options.include,p=o.exclude.length>0?o.exclude:l.options.exclude,m=o.testNamePattern??l.options.testNamePattern,h=o.testTimeout??l.options.testTimeout,g=o.bail||l.options.bail===!0,_=await t({filesystem:r.discoveryFileSystem(s),projectPath:s,...o.files.length>0?{files:o.files}:{},...d===void 0?{}:{include:d},...p===void 0?{}:{exclude:p}});if(_.files.length===0){let e=`No GeoSpec files matched (unmatched: ${_.unmatchedRoots.join(`, `)}).`;return r.write(o.json?JSON.stringify({success:!1,error:e,..._}):e),1}let v=r.createRunner({projectPath:s,configPath:l.configPath,workers:o.workers,shardTimeout:o.shardTimeout}),y;try{y=await v.run({files:_.files,...m===void 0?{}:{testNamePattern:m},...h===void 0?{}:{testTimeout:h},...g?{bail:!0}:{}})}finally{await v.close()}if(o.json)for(let e of f(u(y)))r.write(e);else r.write(c(y).join(`
30
+ `));return+!y.success};export{s as formatFileReport,l as formatRunHeadline,c as formatRunReport,n as geoSpecCliUsage,f as jsonChunks,i as parseGeoSpecCliArguments,p as runGeoSpecCli,u as runReportJson};
@@ -0,0 +1,3 @@
1
+ import { GeoSpecCliHost, runGeoSpecCli } from "./cli.mjs";
2
+ import { NodeGeoSpecCliHostOptions, createNodeGeoSpecCliHost } from "./node-host.mjs";
3
+ export { type GeoSpecCliHost, type NodeGeoSpecCliHostOptions, createNodeGeoSpecCliHost, runGeoSpecCli };
@@ -0,0 +1 @@
1
+ import{runGeoSpecCli as e}from"./cli.mjs";import{createNodeGeoSpecCliHost as t}from"./node-host.mjs";export{t as createNodeGeoSpecCliHost,e as runGeoSpecCli};
@@ -0,0 +1 @@
1
+ export {}
@@ -0,0 +1,2 @@
1
+ #!/usr/bin/env node
2
+ import{runGeoSpecCli as e}from"./cli.mjs";import{createNodeGeoSpecCliHost as t}from"./node-host.mjs";process.exitCode=await e(process.argv.slice(2),t());export{};
@@ -0,0 +1,26 @@
1
+ import { GeoSpecCliHost } from "./cli.mjs";
2
+ //#region src/cli/node-host.d.ts
3
+ /**
4
+ * Options for {@link createNodeGeoSpecCliHost}.
5
+ *
6
+ * @public
7
+ */
8
+ type NodeGeoSpecCliHostOptions = {
9
+ /** Report sink used by embedding hosts and tests; defaults to stdout. */
10
+ readonly reportStream?: (text: string) => void;
11
+ /**
12
+ * URLs of modules each pool worker imports for exporters that precede the config's, so a host such as `tau test`
13
+ * can run a project with no `geospec.config.*` (see `GeoSpecExporterModule` in `geospec/runner/node`).
14
+ */
15
+ readonly exporterModules?: readonly string[];
16
+ };
17
+ /**
18
+ * Build the Node CLI host.
19
+ *
20
+ * @param options - Report sink and host-supplied exporter modules.
21
+ * @returns The host the CLI runs against.
22
+ * @public
23
+ */
24
+ declare const createNodeGeoSpecCliHost: (options?: NodeGeoSpecCliHostOptions) => GeoSpecCliHost;
25
+ //#endregion
26
+ export { NodeGeoSpecCliHostOptions, createNodeGeoSpecCliHost };
@@ -0,0 +1 @@
1
+ import{loadGeoSpecConfig as e}from"../config/node/load.mjs";import{createGeoSpecNodePoolRunner as t}from"../runner/node/pool-runner.mjs";import{readdir as n,stat as r}from"node:fs/promises";import{availableParallelism as i}from"node:os";const a=(a={})=>{let o=a.reportStream??(e=>{process.stdout.write(e)});return{cwd:()=>process.cwd(),write:e=>{o(`${e}\n`)},discoveryFileSystem:()=>({readdir:async e=>n(e),stat:async e=>({kind:(await r(e)).isDirectory()?`directory`:`file`})}),loadConfig:async({projectPath:t,configPath:n})=>e({projectPath:t,...n===void 0?{}:{configPath:n}}),createRunner:({projectPath:e,configPath:n,workers:r,shardTimeout:o})=>t({projectPath:e,...n===void 0?{}:{configPath:n},...a.exporterModules===void 0?{}:{exporterModules:a.exporterModules},workers:r===0?i():r??1,...o===void 0?{}:{shardTimeout:o}})}};export{a as createNodeGeoSpecCliHost};
@@ -0,0 +1 @@
1
+ const e=e=>e instanceof Int8Array||e instanceof Uint8Array||e instanceof Uint8ClampedArray||e instanceof Int16Array||e instanceof Uint16Array||e instanceof Int32Array||e instanceof Uint32Array||e instanceof Float32Array||e instanceof Float64Array;function t(n,r=new WeakSet){if(n==null)return null;if(typeof n==`string`||typeof n==`boolean`)return n;if(typeof n==`number`){if(!Number.isFinite(n))throw TypeError(`GeoSpec engine emitted a non-finite number.`);return n}if(n instanceof Error)return{name:n.name,message:n.message};if(n instanceof RegExp)return{type:`regexp`,pattern:n.source,flags:n.flags};if(e(n))return[...n];if(typeof n!=`object`||r.has(n))throw TypeError(`GeoSpec engine emitted a non-wire value.`);if(r.add(n),Array.isArray(n)){let e=n.map(e=>t(e,r));return r.delete(n),e}let i=Reflect.getPrototypeOf(n);if(i!==Object.prototype&&i!==null)throw TypeError(`GeoSpec engine emitted a non-plain object.`);let a={};for(let[e,i]of Object.entries(n))i!==void 0&&(a[e]=t(i,r));return r.delete(n),a}export{t as protocolWireValue};
@@ -0,0 +1,15 @@
1
+ import { GeoSpecConfig } from "./types.mjs";
2
+ //#region src/config/define-config.d.ts
3
+ /**
4
+ * Type a `geospec.config.*` default export: `export default defineConfig({ testTimeout: 60_000 })`.
5
+ *
6
+ * An identity at runtime. The parameter is not generic, so an object literal gets the excess-property
7
+ * and contextual checks `satisfies GeoSpecConfig` gives, in `.ts` and `.js` alike.
8
+ *
9
+ * @public
10
+ * @param config - The project configuration.
11
+ * @returns The same object.
12
+ */
13
+ declare const defineConfig: (config: GeoSpecConfig) => GeoSpecConfig;
14
+ //#endregion
15
+ export { defineConfig };
@@ -0,0 +1,2 @@
1
+ const e=e=>e,t=`export const defineConfig = (config) => config;
2
+ `;export{e as defineConfig,t as defineConfigBuiltinCode};
@@ -1,2 +1,4 @@
1
- import { GeoSpecConfig, GeoSpecTauProjectDescriptor, LoadGeoSpecConfigOptions, LoadedGeoSpecConfig } from "./types.mjs";
2
- export type { GeoSpecConfig, GeoSpecTauProjectDescriptor, LoadGeoSpecConfigOptions, LoadedGeoSpecConfig };
1
+ import { GeoSpecConfig, GeoSpecConfigData, LoadGeoSpecConfigOptions, LoadedGeoSpecConfig } from "./types.mjs";
2
+ import { defineConfig } from "./define-config.mjs";
3
+ import { ReadGeoSpecConfigOptions, ReadGeoSpecConfigResult, readGeoSpecConfig } from "./read-geospec-config.mjs";
4
+ export { type GeoSpecConfig, type GeoSpecConfigData, type LoadGeoSpecConfigOptions, type LoadedGeoSpecConfig, type ReadGeoSpecConfigOptions, type ReadGeoSpecConfigResult, defineConfig, readGeoSpecConfig };
@@ -1 +1 @@
1
- export{};
1
+ import{defineConfig as e}from"./define-config.mjs";import{readGeoSpecConfig as t}from"./read-geospec-config.mjs";export{e as defineConfig,t as readGeoSpecConfig};
@@ -3,7 +3,8 @@ import { LoadGeoSpecConfigOptions, LoadedGeoSpecConfig } from "../types.mjs";
3
3
  /**
4
4
  * Load one trusted project config using Node's native module loader.
5
5
  *
6
- * Explicit selection or exactly one geospec.config.js/.mjs/.ts/.mts is allowed.
6
+ * Explicit selection or exactly one geospec.config.js/.mjs/.ts/.mts is allowed. A config's
7
+ * `geospec/config` import resolves to this copy when the project has no install of its own.
7
8
  * TypeScript must use erasable syntax; JSON imports use standard attributes.
8
9
  * Executable config/imports are trusted developer code, not sandboxed code.
9
10
  * Node's same-process module cache is unchanged: load once per run and use a
@@ -1 +1 @@
1
- import{resolveGeoSpecConfig as e}from"../validate.mjs";import{realpath as t,stat as n}from"node:fs/promises";import{extname as r,isAbsolute as i,relative as a,resolve as o,sep as s}from"node:path";import{pathToFileURL as c}from"node:url";const l=[`.js`,`.mjs`,`.ts`,`.mts`],u=async e=>{try{return(await n(e)).isFile()}catch(e){if(typeof e==`object`&&e&&`code`in e&&e.code===`ENOENT`)return!1;throw e}},d=async d=>{let f=await t(d.projectPath),p=d.configPath;if(p===void 0){let e=l.map(e=>`geospec.config${e}`),t=(await Promise.all(e.map(async e=>await u(o(f,e))?e:void 0))).filter(e=>e!==void 0);if(t.length>1)throw TypeError(`Multiple GeoSpec configs found: ${t.join(`, `)}. Select configPath explicitly.`);[p]=t}if(p===void 0)return{options:e({},d.overrides)};let m=r(p);if(!l.some(e=>e===m))throw TypeError(`GeoSpec configPath must select a .js, .mjs, .ts or .mts file.`);let h=await t(o(f,p)),g=a(f,h);if(i(g)||g===`..`||g.startsWith(`..${s}`))throw TypeError(`GeoSpec configPath must resolve within projectPath.`);if(!(await n(h)).isFile())throw TypeError(`GeoSpec configPath must select a file.`);let _=await import(c(h).href);return{configPath:h,options:e(_.default,d.overrides)}};export{d as loadGeoSpecConfig};
1
+ import{resolveGeoSpecConfig as e}from"../validate.mjs";import{registerHooks as t}from"node:module";import{realpath as n,stat as r}from"node:fs/promises";import{extname as i,isAbsolute as a,relative as o,resolve as s,sep as c}from"node:path";import{pathToFileURL as l}from"node:url";const u=[`.js`,`.mjs`,`.ts`,`.mts`],d=async e=>{try{return(await r(e)).isFile()}catch(e){if(typeof e==`object`&&e&&`code`in e&&e.code===`ENOENT`)return!1;throw e}},f=`geospec/config`,p=async e=>{let n=import.meta.resolve(f),r=t({resolve(e,t,r){try{return r(e,t)}catch(t){if(e===f&&typeof t==`object`&&t&&`code`in t&&t.code===`ERR_MODULE_NOT_FOUND`)return{url:n,shortCircuit:!0};throw t}}});try{return(await import(l(e).href)).default}finally{r.deregister()}},m=async t=>{let l=await n(t.projectPath),f=t.configPath;if(f===void 0){let e=u.map(e=>`geospec.config${e}`),t=(await Promise.all(e.map(async e=>await d(s(l,e))?e:void 0))).filter(e=>e!==void 0);if(t.length>1)throw TypeError(`Multiple GeoSpec configs found: ${t.join(`, `)}. Select configPath explicitly.`);[f]=t}if(f===void 0)return{options:e({},t.overrides)};let m=i(f);if(!u.some(e=>e===m))throw TypeError(`GeoSpec configPath must select a .js, .mjs, .ts or .mts file.`);let h=await n(s(l,f)),g=o(l,h);if(a(g)||g===`..`||g.startsWith(`..${c}`))throw TypeError(`GeoSpec configPath must resolve within projectPath.`);if(!(await r(h)).isFile())throw TypeError(`GeoSpec configPath must select a file.`);return{configPath:h,options:e(await p(h),t.overrides)}};export{m as loadGeoSpecConfig};
@@ -0,0 +1,47 @@
1
+ import { GeoSpecConfigData } from "./types.mjs";
2
+ import { VmFileSystem } from "@taucad/esbuild/vm";
3
+ //#region src/config/read-geospec-config.d.ts
4
+ /**
5
+ * Outcome of {@link readGeoSpecConfig}. A config the host cannot apply is an expected case with
6
+ * its own recovery, not an error in the run.
7
+ *
8
+ * @public
9
+ */
10
+ type ReadGeoSpecConfigResult = {
11
+ readonly status: 'absent';
12
+ } | {
13
+ readonly status: 'applied';
14
+ readonly configPath: string;
15
+ readonly options: GeoSpecConfigData;
16
+ } | {
17
+ readonly status: 'not-applied';
18
+ readonly configPath: string;
19
+ /**
20
+ * `unresolved-import`: the config imports a package other than `geospec/config`, which only a
21
+ * native run can provide. `invalid`: it does not bundle, throws, or is not a valid config.
22
+ */
23
+ readonly reason: 'unresolved-import' | 'invalid';
24
+ readonly message: string;
25
+ };
26
+ /** Options for {@link readGeoSpecConfig}. @public */
27
+ type ReadGeoSpecConfigOptions = {
28
+ /** The project filesystem; paths are rooted, as the spec VM reads them. */
29
+ readonly filesystem: VmFileSystem;
30
+ /** Rooted directory holding the config, in the filesystem's spelling: `''` for its root, else `'sub/dir'`. */
31
+ readonly projectPath: string;
32
+ };
33
+ /**
34
+ * Read a project's `geospec.config.*` data fields through the spec VM, the same way on every host.
35
+ *
36
+ * Discovery is `loadGeoSpecConfig`'s: exactly one of `geospec.config.{ts,mts,js,mjs}`. The config
37
+ * may import `geospec/config` (for `defineConfig`) and project files, nothing from `node_modules`:
38
+ * imports are detected first, without a network call, so a config with exporters is `not-applied`
39
+ * rather than fetched. `exporters` are never returned; a host that reads the config holds its own.
40
+ *
41
+ * @public
42
+ * @param options - The project filesystem and the rooted project directory.
43
+ * @returns `absent`, `applied` with the data fields, or `not-applied` with the reason.
44
+ */
45
+ declare const readGeoSpecConfig: (options: ReadGeoSpecConfigOptions) => Promise<ReadGeoSpecConfigResult>;
46
+ //#endregion
47
+ export { ReadGeoSpecConfigOptions, ReadGeoSpecConfigResult, readGeoSpecConfig };
@@ -0,0 +1,3 @@
1
+ import{resolveGeoSpecConfig as e}from"./validate.mjs";import{defineConfigBuiltinCode as t}from"./define-config.mjs";import{createEsbuildModuleVm as n}from"@taucad/esbuild/vm";const r=[`geospec.config.ts`,`geospec.config.mts`,`geospec.config.js`,`geospec.config.mjs`],i=async i=>{let{filesystem:a}=i,o=i.projectPath===``?``:`${i.projectPath.replace(/\/+$/u,``)}/`,s=(await Promise.all(r.map(async e=>await a.exists(`${o}${e}`)?`${o}${e}`:void 0))).filter(e=>e!==void 0),[c]=s;if(c===void 0)return{status:`absent`};let l=(e,t)=>({status:`not-applied`,configPath:c,reason:e,message:t});if(s.length>1)return l(`invalid`,`Multiple GeoSpec configs found: ${s.join(`, `)}. Keep one.`);let u=await n({filesystem:a});try{u.registerModule(`geospec/config`,{version:`0.0.0`,code:t});let n;try{({detectedModules:n}=await u.detectImports(c))}catch(e){return l(`invalid`,e instanceof Error?e.message:String(e))}let r=n.filter(e=>e!==`geospec/config`);if(r.length>0)return l(`unresolved-import`,`The GeoSpec config imports ${r.map(e=>`'${e}'`).join(`, `)}, which this host does not provide; only a native run applies it.`);let i=await u.bundle(c);if(!i.success)return l(`invalid`,i.issues.map(({message:e})=>e).join(`
2
+ `));let a=await u.execute(i.code);if(!a.success)return l(`invalid`,a.issues.map(({message:e})=>e).join(`
3
+ `));let{exporters:o,...s}=e(a.value.default);return{status:`applied`,configPath:c,options:s}}catch(e){if(e instanceof TypeError)return l(`invalid`,e.message);throw e}finally{u.dispose()}};export{i as readGeoSpecConfig};