geospec 0.5.0 → 0.5.1-next.342

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

@@ -1414,7 +1414,7 @@ MinimumDistanceResult: {
     readonly fact: MinimumDistanceFact;
 } | {
     readonly status: 'refused';
-    readonly code: 'unsupported-evidence' | 'invalid-selection' | 'work-limit' | 'analysis-limit' | 'resource-limit';
+    readonly code: 'unsupported-evidence' | 'invalid-selection' | 'invalid-expectation' | 'work-limit' | 'analysis-limit' | 'resource-limit';
     readonly message: string;
 } | {
     readonly status: 'interrupted';

package/agent/resources.js

@@ -7,7 +7,7 @@ export default Object.freeze([
     version: "0.5.0",
     whenToUse: "Use before creating or editing *.geospec.ts or *.geospec.js tests, for a model in any kernel.",
     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 the exporter the host or the project's `geospec.config.ts` supplies. On Tau projects that is Tau's runtime, configured in `tau.config.ts`; never set GeoSpec exporters there. `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- An unknown or mistyped expectation field refuses only that claim, with `GEOSPEC_INVALID_EXPECTATION` naming `details.field`; its `test_model` row is inconclusive, category `invalid-expectation`. Fix the expectation and keep the assertion.\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 299 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",
-    fingerprint: "bf979c7645e3f7d89faf2c7bb96477925bec1a146c8a46fd9204c8e46e2b3adb",
+    fingerprint: "d91281a63eef55dd13d0a227e82455c870658e10132effa44fd0590c30df0d06",
     files: Object.freeze([
       Object.freeze({ path: "SKILL.md", url: new URL("./geospec-authoring/SKILL.md", import.meta.url).href, byteLength: 24024, lineCount: 497, contentKind: 'text', mediaType: 'text/markdown', sha256: "19060a4ce60bbb0cc6aba1da7e98f7e17f7de870aa047130a8ae5d58f1ca0845" }),
       Object.freeze({ path: "api-index.md", url: new URL("./geospec-authoring/api-index.md", import.meta.url).href, byteLength: 26968, lineCount: 317, contentKind: 'text', mediaType: 'text/markdown', sha256: "34ca39beb3a46e95769ce4c4fa1c824e1f883d32787a05228afa003e44a9aca9" }),
@@ -19,7 +19,7 @@ export default Object.freeze([
       Object.freeze({ path: "public-api-functions.md", url: new URL("./geospec-authoring/public-api-functions.md", import.meta.url).href, byteLength: 16217, lineCount: 284, contentKind: 'text', mediaType: 'text/markdown', sha256: "8f1d70cc0102025bc6ff6241da48cb9434fdf21155f99f0140510c9f222b8757" }),
       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" }),
       Object.freeze({ path: "public-api-types.md", url: new URL("./geospec-authoring/public-api-types.md", import.meta.url).href, byteLength: 57017, lineCount: 1545, contentKind: 'text', mediaType: 'text/markdown', sha256: "7ccfe6ba33ccb2c15c0576eb24e5c9be0bfc1f7411882850b30a1117676ac46f" }),
-      Object.freeze({ path: "public-api-types-2.md", url: new URL("./geospec-authoring/public-api-types-2.md", import.meta.url).href, byteLength: 54865, lineCount: 1550, contentKind: 'text', mediaType: 'text/markdown', sha256: "746f29b1536e8353407d9985691114cad8d773d7f512d31a2512d3b929d5ef78" }),
+      Object.freeze({ path: "public-api-types-2.md", url: new URL("./geospec-authoring/public-api-types-2.md", import.meta.url).href, byteLength: 54889, lineCount: 1550, contentKind: 'text', mediaType: 'text/markdown', sha256: "656f57c049091e99101055d092428adf8b5bf27fee0383242f74a98622a91c4c" }),
       Object.freeze({ path: "public-api-types-3.md", url: new URL("./geospec-authoring/public-api-types-3.md", import.meta.url).href, byteLength: 15486, lineCount: 439, contentKind: 'text', mediaType: 'text/markdown', sha256: "3314597895a5fddb201401437bb2691b7b56c76e0b314317ac94a14de4507ad6" }),
       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" })
     ]),

package/dist/assertion-client/client.d.mts

@@ -59,7 +59,7 @@ export type MinimumDistanceResult = {
   readonly fact: MinimumDistanceFact;
 } | {
   readonly status: 'refused';
-  readonly code: 'unsupported-evidence' | 'invalid-selection' | 'work-limit' | 'analysis-limit' | 'resource-limit';
+  readonly code: 'unsupported-evidence' | 'invalid-selection' | 'invalid-expectation' | 'work-limit' | 'analysis-limit' | 'resource-limit';
   readonly message: string;
 } | {
   readonly status: 'interrupted';

package/dist/assertion-client/client.mjs

@@ -1,2 +1,2 @@
-import{geoSpecMatcherDescriptors as e,normalizeGeoSpecExpected as t}from"../engine/matchers.mjs";import{assertGeoSpecAuthoredWorkUnitLimit as n,evaluateGeoSpecNativeClaim as r,evaluateGeoSpecNativeQuery as i,resolveGeoSpecMaximumWorkUnitLimit as a,resolveGeoSpecNativeWorkUnitLimit as o,supportsGeoSpecNativeMinimumDistance as s}from"../engine/client.mjs";import{resolveGeoSpecSubject as c}from"../model/subject.mjs";const l=(e,t)=>{if(typeof e!=`object`||!e||Array.isArray(e))return;let{fact:n}=e;if(typeof n!=`object`||!n||Array.isArray(n))return;let{distance:r,points:i,occurrences:a,subjectHash:o}=n,s=e=>Array.isArray(e)&&e.length===3&&e.every(e=>typeof e==`number`&&Number.isFinite(e));if(!(e.profile!==`geospec-minimum-distance-v1`||n.source!==`ap242`||n.assurance!==`exact-brep`||n.unit!==`mm`||n.coordinateSystem!==`z-up`||n.algorithmProfile!==`geospec-minimum-distance-v1`||typeof o!=`string`||!/^[0-9a-f]{64}$/u.test(o)||o!==(t.subject.subjectHash??t.subject.contentHash)||typeof r!=`number`||!Number.isFinite(r)||r<0||!Array.isArray(a)||a.length!==2||a[0]!==t.payload.pair[0].occurrencePath||a[1]!==t.payload.pair[1].occurrencePath||!Array.isArray(i)||i.length!==2||!s(i[0])||!s(i[1])))return{source:`ap242`,assurance:`exact-brep`,unit:`mm`,coordinateSystem:`z-up`,subjectHash:o,algorithmProfile:`geospec-minimum-distance-v1`,occurrences:[a[0],a[1]],distance:r,points:[i[0],i[1]]}},u=(e,t)=>{if(e.status===`passed`){let n=l(e.evidence,t);return n===void 0?{status:`interrupted`,code:`engine-error`,message:`Native minimum returned malformed evidence.`}:{status:`complete`,fact:n}}let n=e.diagnostics.find(e=>typeof e==`object`&&!!e&&!Array.isArray(e)),r=typeof n==`object`&&n&&!Array.isArray(n)?n.code:void 0,i=typeof n==`object`&&n&&!Array.isArray(n)&&typeof n.message==`string`?n.message:`Native minimum is unavailable.`;return r===`GEOSPEC_INVALID_SELECTION`?{status:`refused`,code:`invalid-selection`,message:i}:r===`MATCHER_TIMEOUT`?{status:`refused`,code:`work-limit`,message:i}:r===`GEOSPEC_ANALYSIS_LIMIT`?{status:`refused`,code:`analysis-limit`,message:i}:r===`GEOSPEC_RESOURCE_LIMIT`?{status:`refused`,code:`resource-limit`,message:i}:r===`GEOSPEC_UNSUPPORTED_EVIDENCE`||r===`GEOSPEC_EVIDENCE_UNSUPPORTED`?{status:`refused`,code:`unsupported-evidence`,message:i}:{status:`interrupted`,code:`engine-error`,message:i}};var d=class extends Error{canonicalClaim;canonicalPlan;canonicalResult;claim;diagnostics;report;result;constructor(e){let t=e.diagnostics.flatMap(e=>{if(typeof e!=`object`||!e||Array.isArray(e))return[];let{message:t}=e;return typeof t==`string`?[t]:[]});super(t.join(`
+import{geoSpecMatcherDescriptors as e,normalizeGeoSpecExpected as t}from"../engine/matchers.mjs";import{assertGeoSpecAuthoredWorkUnitLimit as n,evaluateGeoSpecNativeClaim as r,evaluateGeoSpecNativeQuery as i,resolveGeoSpecMaximumWorkUnitLimit as a,resolveGeoSpecNativeWorkUnitLimit as o,supportsGeoSpecNativeMinimumDistance as s}from"../engine/client.mjs";import{resolveGeoSpecSubject as c}from"../model/subject.mjs";const l=(e,t)=>{if(typeof e!=`object`||!e||Array.isArray(e))return;let{fact:n}=e;if(typeof n!=`object`||!n||Array.isArray(n))return;let{distance:r,points:i,occurrences:a,subjectHash:o}=n,s=e=>Array.isArray(e)&&e.length===3&&e.every(e=>typeof e==`number`&&Number.isFinite(e));if(!(e.profile!==`geospec-minimum-distance-v1`||n.source!==`ap242`||n.assurance!==`exact-brep`||n.unit!==`mm`||n.coordinateSystem!==`z-up`||n.algorithmProfile!==`geospec-minimum-distance-v1`||typeof o!=`string`||!/^[0-9a-f]{64}$/u.test(o)||o!==(t.subject.subjectHash??t.subject.contentHash)||typeof r!=`number`||!Number.isFinite(r)||r<0||!Array.isArray(a)||a.length!==2||a[0]!==t.payload.pair[0].occurrencePath||a[1]!==t.payload.pair[1].occurrencePath||!Array.isArray(i)||i.length!==2||!s(i[0])||!s(i[1])))return{source:`ap242`,assurance:`exact-brep`,unit:`mm`,coordinateSystem:`z-up`,subjectHash:o,algorithmProfile:`geospec-minimum-distance-v1`,occurrences:[a[0],a[1]],distance:r,points:[i[0],i[1]]}},u=(e,t)=>{if(e.status===`passed`){let n=l(e.evidence,t);return n===void 0?{status:`interrupted`,code:`engine-error`,message:`Native minimum returned malformed evidence.`}:{status:`complete`,fact:n}}let n=e.diagnostics.find(e=>typeof e==`object`&&!!e&&!Array.isArray(e)),r=typeof n==`object`&&n&&!Array.isArray(n)?n.code:void 0,i=typeof n==`object`&&n&&!Array.isArray(n)&&typeof n.message==`string`?n.message:`Native minimum is unavailable.`;return r===`GEOSPEC_INVALID_SELECTION`?{status:`refused`,code:`invalid-selection`,message:i}:r===`GEOSPEC_INVALID_EXPECTATION`?{status:`refused`,code:`invalid-expectation`,message:i}:r===`MATCHER_TIMEOUT`?{status:`refused`,code:`work-limit`,message:i}:r===`GEOSPEC_ANALYSIS_LIMIT`?{status:`refused`,code:`analysis-limit`,message:i}:r===`GEOSPEC_RESOURCE_LIMIT`?{status:`refused`,code:`resource-limit`,message:i}:r===`GEOSPEC_UNSUPPORTED_EVIDENCE`||r===`GEOSPEC_EVIDENCE_UNSUPPORTED`?{status:`refused`,code:`unsupported-evidence`,message:i}:{status:`interrupted`,code:`engine-error`,message:i}};var d=class extends Error{canonicalClaim;canonicalPlan;canonicalResult;claim;diagnostics;report;result;constructor(e){let t=e.diagnostics.flatMap(e=>{if(typeof e!=`object`||!e||Array.isArray(e))return[];let{message:t}=e;return typeof t==`string`?[t]:[]});super(t.join(`
 `)||`GeoSpec assertion '${e.claimId}' ended with status '${e.status}'.`),this.name=`GeoSpecAssertionError`,this.report=e,this.diagnostics=e.diagnostics,this.claim=e.claim,this.result=e.result,this.canonicalClaim=e.canonicalClaim,this.canonicalPlan=e.canonicalPlan,this.canonicalResult=e.canonicalResult}};const f=[`x`,`y`,`z`],p=e=>{if(typeof e!=`object`||!e||!(`point`in e))return;let{point:t}=e,n=Array.isArray(t)?t.map((e,t)=>[f[t]??String(t),e]):typeof t==`object`&&t?Object.entries(t):[];if(n.length===0&&!(typeof t==`object`&&t))throw TypeError(`GeoSpec matcher toHaveCenterOfMass needs point as [x, y, z] or { x, y, z } in millimetres, with an optional tolerance.`);for(let[e,t]of n)if(!(typeof t==`number`&&Number.isFinite(t)))throw TypeError(typeof t==`object`&&t&&!Array.isArray(t)?`GeoSpec matcher toHaveCenterOfMass point.${e} must be a finite number in millimetres: per-axis ranges such as { greaterThan } are not supported for center of mass. Assert the expected point with a tolerance instead.`:`GeoSpec matcher toHaveCenterOfMass point.${e} must be a finite number in millimetres.`)},m=n=>{let r={};for(let i of Object.keys(e)){let a=e[i];r[i]=(...e)=>{if(a.expected===`true`&&e.length>0)throw TypeError(`GeoSpec matcher ${i} does not accept arguments.`);return i===`toHaveCenterOfMass`&&p(e[0]),n.invoke({arguments:e,expected:t(a.expected,e),kind:a.kind,matcher:i,polarity:n.polarity,subject:n.subject})}}return r},h=e=>{let t=0,l=e.subjectSlot??`subject`,f,p=()=>(f??=a(e.maximumWorkUnitLimit),f),h,g=()=>(h??=o(e.engine,e.workUnitLimit),h),_=(n,i,a)=>m({subject:n,polarity:i,invoke:o=>{a.validate(),t+=1;let s={claimId:e.claimId?.(o.matcher,t)??`geospec-claim-${t}`,engine:e.engine,...e.evidenceProfile===void 0?{}:{evidenceProfile:e.evidenceProfile},polarity:i,subject:n,subjectSlot:l,workUnitLimit:a.workUnitLimit??g(),maximumWorkUnitLimit:p()},c=r({...s,arguments:o.arguments,capability:o.matcher,kind:o.kind});if(c.status!==`passed`)throw new d(c);return c}});async function v(n){let r=`claimId`in n?n.claimId??`geospec-claim-${++t}`:`geospec-claim-${++t}`;if(n.capability===`minimumDistance`){let t=n.payload?.pair,r=e=>{if(typeof e==`object`&&e&&`occurrencePath`in e)return typeof e.occurrencePath==`string`&&e.occurrencePath.length>0?e.occurrencePath:void 0};if(!Array.isArray(t)||t.length!==2||r(t[0])===void 0||r(t[1])===void 0||r(t[0])===r(t[1]))return{status:`refused`,code:`invalid-selection`,message:`Select two distinct resolved AP242 occurrence paths.`};try{if(!s(e.engine))return{status:`refused`,code:`unsupported-evidence`,message:`This native engine does not advertise the complete minimum-distance profile.`}}catch{return{status:`refused`,code:`unsupported-evidence`,message:`This native engine cannot negotiate the complete minimum-distance profile.`}}}try{let t=i({capability:n.capability,claimId:r,engine:e.engine,...e.evidenceProfile===void 0?{}:{evidenceProfile:e.evidenceProfile},payload:n.payload,subject:n.subject,subjectSlot:l,workUnitLimit:g()});return n.capability===`minimumDistance`?u(t,n):t}catch(e){if(n.capability!==`minimumDistance`)throw e;return{status:`interrupted`,code:`engine-error`,message:e instanceof Error?e.message:`Native minimum query failed.`}}}return{query:v,expectGeo(t,r){n(r?.workUnitLimit,`expectGeo workUnitLimit`,p());let i=`subjectHash`in t||`contentHash`in t,a=i?void 0:c(t,e.engine),o=i?t:a.identity,s={validate:()=>{i||c(t,e.engine)},workUnitLimit:r?.workUnitLimit??a?.load?.workUnitLimit},l=_(o,`positive`,s);return Object.assign(l,{not:_(o,`negative`,s)})}}};export{d as GeoSpecAssertionError,h as createGeoSpecAssertionClient,m as createGeoSpecMatcherMethods};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "geospec",
-  "version": "0.5.0",
+  "version": "0.5.1-next.342",
   "description": "Geometry specification API for CAD models: DSL, selector language, diagnostics schema, and the native runner integration",
   "type": "module",
   "sideEffects": [
@@ -125,7 +125,7 @@
   "dependencies": {
     "esbuild": "0.28.2",
     "zod": "4.6.7",
-    "geospec-engine": "0.5.0"
+    "geospec-engine": "0.5.1-next.342"
   },
   "devDependencies": {
     "@gltf-transform/core": "4.5.1",