geospec 0.1.0-beta.7 → 0.1.0-beta.8

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 (52) hide show
  1. package/agent/geospec-authoring/SKILL.md +11 -11
  2. package/agent/geospec-authoring/api-functions.md +1 -16
  3. package/agent/geospec-authoring/api-index.md +50 -46
  4. package/agent/geospec-authoring/api-types.md +188 -168
  5. package/agent/geospec-authoring/public-api-functions.md +29 -22
  6. package/agent/geospec-authoring/public-api-index.md +196 -183
  7. package/agent/geospec-authoring/public-api-types-2.md +188 -220
  8. package/agent/geospec-authoring/public-api-types-3.md +112 -99
  9. package/agent/geospec-authoring/public-api-types.md +236 -125
  10. package/agent/resources.js +12 -12
  11. package/agent/skills.json +2 -2
  12. package/dist/config/index.d.mts +1 -2
  13. package/dist/config/index.mjs +1 -1
  14. package/dist/config/types.d.mts +0 -3
  15. package/dist/config/validate.mjs +1 -1
  16. package/dist/mesh/index.d.mts +2 -2
  17. package/dist/model/index.d.mts +3 -3
  18. package/dist/model/index.mjs +1 -1
  19. package/dist/model/mesh-evidence-matchers.d.mts +12 -0
  20. package/dist/model/mesh-evidence-matchers.mjs +1 -0
  21. package/dist/model/native-model-loader.d.mts +8 -8
  22. package/dist/model/native-model-loader.mjs +1 -1
  23. package/dist/model/node/command-exporter.d.mts +31 -0
  24. package/dist/model/node/command-exporter.mjs +1 -0
  25. package/dist/model/node/index.d.mts +2 -0
  26. package/dist/model/node/index.mjs +1 -0
  27. package/dist/model/types.d.mts +111 -63
  28. package/dist/runner/collector.d.mts +0 -2
  29. package/dist/runner/node/index.d.mts +2 -0
  30. package/dist/runner/node/index.mjs +1 -0
  31. package/dist/runner/node/node-vm-filesystem.d.mts +22 -0
  32. package/dist/runner/node/node-vm-filesystem.mjs +1 -0
  33. package/dist/runner/pool/events.mjs +1 -0
  34. package/dist/runner/pool/pool-messages.d.mts +0 -10
  35. package/dist/runner/pool/pool.d.mts +36 -0
  36. package/dist/runner/pool/pool.mjs +1 -0
  37. package/dist/runner/pool/shard-planner.mjs +1 -0
  38. package/dist/runner/pool/shard-timings.d.mts +36 -0
  39. package/dist/runner/pool/transport.mjs +1 -0
  40. package/dist/runner/pool/worker-host.d.mts +36 -0
  41. package/dist/runner/pool/worker-host.mjs +1 -0
  42. package/dist/runner/run-geospec-module.mjs +1 -1
  43. package/dist/runner/types.d.mts +0 -4
  44. package/dist/runner/worker/index.d.mts +5 -2
  45. package/dist/runner/worker/index.mjs +1 -1
  46. package/dist/runner/worker/runner-types.d.mts +2 -14
  47. package/dist/runner/worker/serial-runner.mjs +1 -1
  48. package/package.json +14 -4
  49. package/dist/config/tau-project-artifact.d.mts +0 -54
  50. package/dist/config/tau-project-artifact.mjs +0 -3
  51. package/dist/model/export-intent.d.mts +0 -79
  52. package/dist/model/export-intent.mjs +0 -1
@@ -4,23 +4,23 @@ 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.7",
7
+ version: "0.1.0-beta.8",
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 runtime\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\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// Inline code-CAD model load options\nLoadModelCodeOptions: {\n // Source files keyed by project-relative path\n code: Code\n // Geometry format to export\n format?: GeoSpecModelFormat\n // Explicit parameters passed to the runtime\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: file, rootDir, runtime, sourceAdapters, projectPath, stepStreaming, meshLinearTolerance, meshAngularToleranceDegrees, workUnitLimit, region\n}\n\nRuntimeBackedModelFormat: Exclude<GeoSpecModelFormat, 'mesh-buffer'>\n```\n\n## API reference\n\nTo read any other signature, find its name in `api-index.md`, which lists all 364 symbols by file with the lines that hold each, and read that range of the named file.\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: "51b3bf4942f7eb6aa3c9907f5c900796bc7d65b8f141d1f1055579ebb4980f9a",
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",
11
11
  files: Object.freeze([
12
- Object.freeze({ path: "SKILL.md", url: new URL("./geospec-authoring/SKILL.md", import.meta.url).href, byteLength: 23589, lineCount: 496, contentKind: 'text', mediaType: 'text/markdown', sha256: "93fe59244e945e0f2ae78a01a63ab5e7711d4eca67d63c84403ef5064c8b14b9" }),
13
- Object.freeze({ path: "api-index.md", url: new URL("./geospec-authoring/api-index.md", import.meta.url).href, byteLength: 29905, lineCount: 382, contentKind: 'text', mediaType: 'text/markdown', sha256: "97000dbdcc54be50157559d77e3323347bcd3cb1e69847a479b5e261aaff1d84" }),
14
- Object.freeze({ path: "api-functions.md", url: new URL("./geospec-authoring/api-functions.md", import.meta.url).href, byteLength: 2549, lineCount: 58, contentKind: 'text', mediaType: 'text/markdown', sha256: "733e9de321d6d1cc3db03a20af5ac211747dfc421f6091f461ed6629e8501d71" }),
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" }),
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: 61112, lineCount: 1817, contentKind: 'text', mediaType: 'text/markdown', sha256: "2841da4ddb764dca62a3137ceb59328867a3bf1496ad395219407cc7fa35def1" }),
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" }),
17
17
  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: 68008, lineCount: 899, contentKind: 'text', mediaType: 'text/markdown', sha256: "61043425364c8895fb6781a43938ca72898f314d91bdd394eeb1890a108cdf3d" }),
19
- Object.freeze({ path: "public-api-functions.md", url: new URL("./geospec-authoring/public-api-functions.md", import.meta.url).href, byteLength: 11567, lineCount: 216, contentKind: 'text', mediaType: 'text/markdown', sha256: "a1a4e17ba9b9f2f2b997702f6b203da880efe65e7bf8d69c6bfab0b6e41d525d" }),
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" }),
20
20
  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: 59455, lineCount: 1949, contentKind: 'text', mediaType: 'text/markdown', sha256: "783ae4f4526780306cd63a87d52e7e108997d38b1892e73bd5587937c0da552b" }),
22
- Object.freeze({ path: "public-api-types-2.md", url: new URL("./geospec-authoring/public-api-types-2.md", import.meta.url).href, byteLength: 54529, lineCount: 1528, contentKind: 'text', mediaType: 'text/markdown', sha256: "5619a3cc1743d704c77bff0eb9ac51d5deac2dc6562d5fca5900a32ce5db1178" }),
23
- Object.freeze({ path: "public-api-types-3.md", url: new URL("./geospec-authoring/public-api-types-3.md", import.meta.url).href, byteLength: 9547, lineCount: 282, contentKind: 'text', mediaType: 'text/markdown', sha256: "b40b66a4ca44aa55f0fa9a4ebd1f286cf6db05583fb7c97c67629771f53b67f5" }),
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" }),
24
24
  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
25
  ]),
26
26
  }),
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.7",
7
+ "version": "0.1.0-beta.8",
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": [
@@ -22,7 +22,7 @@
22
22
  "public-api-types-3.md",
23
23
  "public-api-classes.md"
24
24
  ],
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 runtime\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\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// Inline code-CAD model load options\nLoadModelCodeOptions: {\n // Source files keyed by project-relative path\n code: Code\n // Geometry format to export\n format?: GeoSpecModelFormat\n // Explicit parameters passed to the runtime\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: file, rootDir, runtime, sourceAdapters, projectPath, stepStreaming, meshLinearTolerance, meshAngularToleranceDegrees, workUnitLimit, region\n}\n\nRuntimeBackedModelFormat: Exclude<GeoSpecModelFormat, 'mesh-buffer'>\n```\n\n## API reference\n\nTo read any other signature, find its name in `api-index.md`, which lists all 364 symbols by file with the lines that hold each, and read that range of the named file.\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"
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
26
  }
27
27
  ]
28
28
  }
@@ -1,3 +1,2 @@
1
1
  import { GeoSpecConfig, GeoSpecTauProjectDescriptor, LoadGeoSpecConfigOptions, LoadedGeoSpecConfig } from "./types.mjs";
2
- import { ExportTauProjectArtifactOptions, GeoSpecTauProjectArtifact, GeoSpecTauProjectRuntime, exportTauProjectArtifact } from "./tau-project-artifact.mjs";
3
- export { type ExportTauProjectArtifactOptions, type GeoSpecConfig, type GeoSpecTauProjectArtifact, type GeoSpecTauProjectDescriptor, type GeoSpecTauProjectRuntime, type LoadGeoSpecConfigOptions, type LoadedGeoSpecConfig, exportTauProjectArtifact };
2
+ export type { GeoSpecConfig, GeoSpecTauProjectDescriptor, LoadGeoSpecConfigOptions, LoadedGeoSpecConfig };
@@ -1 +1 @@
1
- import{exportTauProjectArtifact as e}from"./tau-project-artifact.mjs";export{e as exportTauProjectArtifact};
1
+ export{};
@@ -31,10 +31,7 @@ type GeoSpecConfig = {
31
31
  testNamePattern?: string;
32
32
  /** Positive finite milliseconds; the runner owns its default. */
33
33
  testTimeout?: number;
34
- /** Positive finite milliseconds; does not define a geometry verdict. */
35
- matcherWallBackstop?: number;
36
34
  bail?: boolean;
37
- forensic?: boolean;
38
35
  cache?: boolean;
39
36
  /** Requested cache location only; loading configuration creates no store. */
40
37
  cacheDirectory?: string;
@@ -1 +1 @@
1
- import{assertGeoSpecJsonValue as e}from"../engine/protocol.mjs";const t=(e,t)=>{if(typeof e!=`object`||!e||Array.isArray(e))throw TypeError(`${t} must be a plain object.`);let n=Object.getPrototypeOf(e);if(n!==Object.prototype&&n!==null)throw TypeError(`${t} must be a plain object.`);return e},n=(n,r)=>{let i=t(n,r);return e(i),i},r=e=>{let r=t(e,`GeoSpec Tau descriptor`);for(let e of Reflect.ownKeys(r))if(typeof e!=`string`||![`kind`,`manifestPath`,`manifest`,`format`,`parameters`].includes(e))throw TypeError(`Unsupported GeoSpec Tau descriptor field '${String(e)}'.`);let{kind:i,manifestPath:a,manifest:o,format:s,parameters:c}=r;if(i!==`tau-project`)throw TypeError(`GeoSpec Tau descriptor kind must be 'tau-project'.`);if(typeof a!=`string`||a.length===0||a.length>2048||a.includes(`\0`)||a.includes(`\\`)||a.startsWith(`/`)||a.split(`/`).some(e=>e.length===0||e===`.`||e===`..`))throw TypeError(`GeoSpec manifestPath must be a normalized project-relative POSIX path.`);if(s!==`step`&&s!==`glb`)throw TypeError(`GeoSpec Tau descriptor format must be 'step' or 'glb'.`);return{kind:i,manifestPath:a,manifest:n(o,`GeoSpec manifest`),format:s,...c===void 0?{}:{parameters:n(c,`GeoSpec parameters`)}}},i=e=>{let n=t(e,`GeoSpec config`),i={};for(let e of Reflect.ownKeys(n)){if(typeof e!=`string`)throw TypeError(`Unsupported GeoSpec config field '${String(e)}'.`);let a=n[e];switch(e){case`include`:case`exclude`:{if(a===void 0)break;if(!Array.isArray(a))throw TypeError(`GeoSpec ${e} must be an array of strings.`);let t=[...a];if(!t.every(e=>typeof e==`string`))throw TypeError(`GeoSpec ${e} must be an array of strings.`);i[e]=t;break}case`testNamePattern`:case`cacheDirectory`:if(a===void 0)break;if(typeof a!=`string`)throw TypeError(`GeoSpec ${e} must be a string.`);i[e]=a;break;case`testTimeout`:case`matcherWallBackstop`:if(a===void 0)break;if(typeof a!=`number`||!Number.isFinite(a)||a<=0)throw TypeError(`GeoSpec ${e} must be positive finite milliseconds.`);i[e]=a;break;case`bail`:case`forensic`:case`cache`:if(a===void 0)break;if(typeof a!=`boolean`)throw TypeError(`GeoSpec ${e} must be a boolean.`);i[e]=a;break;case`subjects`:{if(a===void 0)break;let e=t(a,`GeoSpec subjects`);i.subjects=Object.fromEntries(Reflect.ownKeys(e).map(t=>{if(typeof t!=`string`)throw TypeError(`GeoSpec subjects keys must be strings.`);return[t,r(e[t])]}));break}default:throw TypeError(`Unsupported GeoSpec config field '${e}'.`)}}return i},a=(e,t={})=>({...i(e),...i(t)});export{a as resolveGeoSpecConfig};
1
+ import{assertGeoSpecJsonValue as e}from"../engine/protocol.mjs";const t=(e,t)=>{if(typeof e!=`object`||!e||Array.isArray(e))throw TypeError(`${t} must be a plain object.`);let n=Object.getPrototypeOf(e);if(n!==Object.prototype&&n!==null)throw TypeError(`${t} must be a plain object.`);return e},n=(n,r)=>{let i=t(n,r);return e(i),i},r=e=>{let r=t(e,`GeoSpec Tau descriptor`);for(let e of Reflect.ownKeys(r))if(typeof e!=`string`||![`kind`,`manifestPath`,`manifest`,`format`,`parameters`].includes(e))throw TypeError(`Unsupported GeoSpec Tau descriptor field '${String(e)}'.`);let{kind:i,manifestPath:a,manifest:o,format:s,parameters:c}=r;if(i!==`tau-project`)throw TypeError(`GeoSpec Tau descriptor kind must be 'tau-project'.`);if(typeof a!=`string`||a.length===0||a.length>2048||a.includes(`\0`)||a.includes(`\\`)||a.startsWith(`/`)||a.split(`/`).some(e=>e.length===0||e===`.`||e===`..`))throw TypeError(`GeoSpec manifestPath must be a normalized project-relative POSIX path.`);if(s!==`step`&&s!==`glb`)throw TypeError(`GeoSpec Tau descriptor format must be 'step' or 'glb'.`);return{kind:i,manifestPath:a,manifest:n(o,`GeoSpec manifest`),format:s,...c===void 0?{}:{parameters:n(c,`GeoSpec parameters`)}}},i=e=>{let n=t(e,`GeoSpec config`),i={};for(let e of Reflect.ownKeys(n)){if(typeof e!=`string`)throw TypeError(`Unsupported GeoSpec config field '${String(e)}'.`);let a=n[e];switch(e){case`include`:case`exclude`:{if(a===void 0)break;if(!Array.isArray(a))throw TypeError(`GeoSpec ${e} must be an array of strings.`);let t=[...a];if(!t.every(e=>typeof e==`string`))throw TypeError(`GeoSpec ${e} must be an array of strings.`);i[e]=t;break}case`testNamePattern`:case`cacheDirectory`:if(a===void 0)break;if(typeof a!=`string`)throw TypeError(`GeoSpec ${e} must be a string.`);i[e]=a;break;case`testTimeout`:if(a===void 0)break;if(typeof a!=`number`||!Number.isFinite(a)||a<=0)throw TypeError(`GeoSpec ${e} must be positive finite milliseconds.`);i[e]=a;break;case`bail`:case`cache`:if(a===void 0)break;if(typeof a!=`boolean`)throw TypeError(`GeoSpec ${e} must be a boolean.`);i[e]=a;break;case`subjects`:{if(a===void 0)break;let e=t(a,`GeoSpec subjects`);i.subjects=Object.fromEntries(Reflect.ownKeys(e).map(t=>{if(typeof t!=`string`)throw TypeError(`GeoSpec subjects keys must be strings.`);return[t,r(e[t])]}));break}default:throw TypeError(`Unsupported GeoSpec config field '${e}'.`)}}return i},a=(e,t={})=>({...i(e),...i(t)});export{a as resolveGeoSpecConfig};
@@ -1,4 +1,4 @@
1
1
  import { GeoSpecUnit } from "../geometry-unit.mjs";
2
- import { AabbMeters, BoundingBoxAxisExtremum, BoundingBoxAxisFailure, BoundingBoxFailure, BoundingBoxStats, BrepEvidence, CheckResult, ClusterGap, ClusterReport, ConnectedComponentsFailure, ConnectedComponentsResult, GeometryCapability, GeometryDiagnostic, GeometryEvidenceDiagnostic, GeometryFileFormat, GeometryProvenance, GeometrySource, GeometryStats, GeometrySubject, GeometrySubjectMeshEvidence, MeshEvidence, MeshFileFormat, MeshQualityStats, MeshTriangle, PrimitiveRecord, StepEvidence, Vec3, WatertightFailure, WatertightIrregularEdgeCluster, WatertightIrregularEdgeKind, WatertightIrregularEdgeSample, WatertightPrimitiveBreakdown, WatertightResult } from "./types.mjs";
2
+ import { AabbMeters, BoundingBoxAxisExtremum, BoundingBoxAxisFailure, BoundingBoxFailure, BoundingBoxStats, BrepEvidence, CheckResult, ClusterGap, ClusterReport, ConnectedComponentsFailure, ConnectedComponentsResult, GeometryCapability, GeometryDiagnostic, GeometryEvidenceDiagnostic, GeometryExportIntent, GeometryFileFormat, GeometryProvenance, GeometrySource, GeometryStats, GeometrySubject, GeometrySubjectMeshEvidence, MeshEvidence, MeshFileFormat, MeshQualityStats, MeshTriangle, PrimitiveRecord, StepEvidence, Vec3, WatertightFailure, WatertightIrregularEdgeCluster, WatertightIrregularEdgeKind, WatertightIrregularEdgeSample, WatertightPrimitiveBreakdown, WatertightResult } from "./types.mjs";
3
3
  import { MeshBufferSource, MeshSource } from "../model/types.mjs";
4
- export type { AabbMeters, BoundingBoxAxisExtremum, BoundingBoxAxisFailure, BoundingBoxFailure, BoundingBoxStats, BrepEvidence, CheckResult, ClusterGap, ClusterReport, ConnectedComponentsFailure, ConnectedComponentsResult, GeoSpecUnit, GeometryCapability, GeometryDiagnostic, GeometryEvidenceDiagnostic, GeometryFileFormat, GeometryProvenance, GeometrySource, GeometryStats, GeometrySubject, GeometrySubjectMeshEvidence, MeshBufferSource, MeshEvidence, MeshFileFormat, MeshQualityStats, MeshSource, MeshTriangle, PrimitiveRecord, StepEvidence, Vec3, WatertightFailure, WatertightIrregularEdgeCluster, WatertightIrregularEdgeKind, WatertightIrregularEdgeSample, WatertightPrimitiveBreakdown, WatertightResult };
4
+ export type { AabbMeters, BoundingBoxAxisExtremum, BoundingBoxAxisFailure, BoundingBoxFailure, BoundingBoxStats, BrepEvidence, CheckResult, ClusterGap, ClusterReport, ConnectedComponentsFailure, ConnectedComponentsResult, GeoSpecUnit, GeometryCapability, GeometryDiagnostic, GeometryEvidenceDiagnostic, GeometryExportIntent, GeometryFileFormat, GeometryProvenance, GeometrySource, GeometryStats, GeometrySubject, GeometrySubjectMeshEvidence, MeshBufferSource, MeshEvidence, MeshFileFormat, MeshQualityStats, MeshSource, MeshTriangle, PrimitiveRecord, StepEvidence, Vec3, WatertightFailure, WatertightIrregularEdgeCluster, WatertightIrregularEdgeKind, WatertightIrregularEdgeSample, WatertightPrimitiveBreakdown, WatertightResult };
@@ -1,7 +1,7 @@
1
1
  import { GeoSpecSubject } from "./subject.mjs";
2
- import { CreateModelLoaderOptions, GeoSpecLoadRegion, GeoSpecModelFormat, GeoSpecModelLoader, GeoSpecRuntimeClient, GeoSpecRuntimeClientFactory, GeoSpecRuntimeSourceAdapter, LoadModelCodeOptions, LoadModelFileOptions, LoadModelOptions, LoadModelSourceOptions, ManagedGeoSpecModelLoader } from "./types.mjs";
3
- import { GeoSpecExportRoute, RuntimeBackedModelFormat, RuntimeClientWithRoutes, RuntimeExportIntent, RuntimeExportIntentFailure, geoSpecMeshEvidenceMatchers, resolveRuntimeExportIntent } from "./export-intent.mjs";
2
+ import { CreateModelLoaderOptions, GeoSpecConsumedSources, GeoSpecExportFormat, GeoSpecExporterCapabilities, GeoSpecLoadRegion, GeoSpecModelArtifact, GeoSpecModelExportRequest, GeoSpecModelExporter, GeoSpecModelFormat, GeoSpecModelLoader, LoadModelCodeOptions, LoadModelFileOptions, LoadModelOptions, LoadModelSourceOptions, ManagedGeoSpecModelLoader } from "./types.mjs";
4
3
  import { GeoSpecModelLoadError } from "./errors.mjs";
5
4
  import { createModelLoader, loadModel } from "./load-model.mjs";
5
+ import { geoSpecMeshEvidenceMatchers } from "./mesh-evidence-matchers.mjs";
6
6
  import { geoSpecRegionScopedKinds, geoSpecRegionWholeModelClaimCode } from "./region-scope.mjs";
7
- export { type CreateModelLoaderOptions, type GeoSpecExportRoute, type GeoSpecLoadRegion, type GeoSpecModelFormat, GeoSpecModelLoadError, type GeoSpecModelLoader, type GeoSpecRuntimeClient, type GeoSpecRuntimeClientFactory, type GeoSpecRuntimeSourceAdapter, type GeoSpecSubject, type LoadModelCodeOptions, type LoadModelFileOptions, type LoadModelOptions, type LoadModelSourceOptions, type ManagedGeoSpecModelLoader, type RuntimeBackedModelFormat, type RuntimeClientWithRoutes, type RuntimeExportIntent, type RuntimeExportIntentFailure, createModelLoader, geoSpecMeshEvidenceMatchers, geoSpecRegionScopedKinds, geoSpecRegionWholeModelClaimCode, loadModel, resolveRuntimeExportIntent };
7
+ export { type CreateModelLoaderOptions, type GeoSpecConsumedSources, type GeoSpecExportFormat, type GeoSpecExporterCapabilities, type GeoSpecLoadRegion, type GeoSpecModelArtifact, type GeoSpecModelExportRequest, type GeoSpecModelExporter, type GeoSpecModelFormat, GeoSpecModelLoadError, type GeoSpecModelLoader, type GeoSpecSubject, type LoadModelCodeOptions, type LoadModelFileOptions, type LoadModelOptions, type LoadModelSourceOptions, type ManagedGeoSpecModelLoader, createModelLoader, geoSpecMeshEvidenceMatchers, geoSpecRegionScopedKinds, geoSpecRegionWholeModelClaimCode, loadModel };
@@ -1 +1 @@
1
- import{GeoSpecModelLoadError as e}from"./errors.mjs";import{geoSpecRegionScopedKinds as t,geoSpecRegionWholeModelClaimCode as n}from"./region-scope.mjs";import{geoSpecMeshEvidenceMatchers as r,resolveRuntimeExportIntent as i}from"./export-intent.mjs";import{createModelLoader as a,loadModel as o}from"./load-model.mjs";export{e as GeoSpecModelLoadError,a as createModelLoader,r as geoSpecMeshEvidenceMatchers,t as geoSpecRegionScopedKinds,n as geoSpecRegionWholeModelClaimCode,o as loadModel,i as resolveRuntimeExportIntent};
1
+ import{GeoSpecModelLoadError as e}from"./errors.mjs";import{geoSpecRegionScopedKinds as t,geoSpecRegionWholeModelClaimCode as n}from"./region-scope.mjs";import{createModelLoader as r,loadModel as i}from"./load-model.mjs";import{geoSpecMeshEvidenceMatchers as a}from"./mesh-evidence-matchers.mjs";export{e as GeoSpecModelLoadError,r as createModelLoader,a as geoSpecMeshEvidenceMatchers,t as geoSpecRegionScopedKinds,n as geoSpecRegionWholeModelClaimCode,i as loadModel};
@@ -0,0 +1,12 @@
1
+ //#region src/model/mesh-evidence-matchers.d.ts
2
+ /**
3
+ * The matchers mesh evidence answers, as the GeoSpec authoring skill lists
4
+ * them (`packages/geospec/agent/geospec-authoring/SKILL.md`): bounds, volume,
5
+ * surface area, connected components and watertightness. Every other
6
+ * exact-feature matcher needs STEP BRep evidence.
7
+ *
8
+ * @public
9
+ */
10
+ declare const geoSpecMeshEvidenceMatchers: readonly ["toHaveBoundingBox", "toHaveVolume", "toHaveSurfaceArea", "toHaveConnectedComponents", "toBeWatertight"];
11
+ //#endregion
12
+ export { geoSpecMeshEvidenceMatchers };
@@ -0,0 +1 @@
1
+ const e=[`toHaveBoundingBox`,`toHaveVolume`,`toHaveSurfaceArea`,`toHaveConnectedComponents`,`toBeWatertight`];export{e as geoSpecMeshEvidenceMatchers};
@@ -1,4 +1,4 @@
1
- import { GeoSpecLoadRegion, GeoSpecModelFormat, GeoSpecRuntimeClient, GeoSpecRuntimeClientFactory, GeoSpecRuntimeSourceAdapter, LoadModelOptions, LoadModelSourceOptions } from "./types.mjs";
1
+ import { GeoSpecLoadRegion, GeoSpecModelExporter, GeoSpecModelFormat, LoadModelOptions, LoadModelSourceOptions } from "./types.mjs";
2
2
  import { GeoSpecNativeEngine, GeoSpecNativeSubject } from "../engine/client.mjs";
3
3
  import "../assertion-client/index.mjs";
4
4
  import { SourceRevision } from "@taucad/runtime/types";
@@ -58,7 +58,7 @@ type GeoSpecModelLoadEvidence = {
58
58
  readonly name: string;
59
59
  readonly sha256: string;
60
60
  readonly byteLength: number;
61
- /** Actual source locator consumed by a direct load; absent for bytes and Runtime exports. */
61
+ /** Actual source locator consumed by a direct load; absent for bytes and exports. */
62
62
  readonly sourcePath?: string;
63
63
  }>;
64
64
  };
@@ -78,8 +78,8 @@ type CreateGeoSpecNativeModelLoaderOptions = {
78
78
  readonly format?: Extract<GeoSpecModelFormat, 'glb' | 'step' | 'stp'>;
79
79
  readonly projectPath?: string;
80
80
  readonly readSource?: GeoSpecNativeSourceReader;
81
- readonly runtime?: GeoSpecRuntimeClient | GeoSpecRuntimeClientFactory;
82
- readonly sourceAdapters?: readonly GeoSpecRuntimeSourceAdapter[];
81
+ /** Model exporters for source-kind files; the first whose `extensions` claim the file exports it. */
82
+ readonly exporters?: readonly GeoSpecModelExporter[];
83
83
  /**
84
84
  * Subject handles carried between the release scopes of loaders that share one engine, keyed by
85
85
  * subjectHash. With a carrier, `releaseAll` keeps this scope's subjects for the next scope and
@@ -100,11 +100,11 @@ type CreateGeoSpecNativeModelLoaderOptions = {
100
100
  * Direct `source` loads read their source again on every call and the engine
101
101
  * digests those exact bytes; bytes equal to an admitted subject's reuse that
102
102
  * subject by digest, length and descriptor, and edited bytes admit a new
103
- * subject. Runtime loads are coalesced per release scope (one run): a load
103
+ * subject. Exported loads are coalesced per release scope (one run): a load
104
104
  * whose file, inline code, project path, parameters, format, tolerances,
105
105
  * region and ingest options equal an earlier successful load's reuses that
106
106
  * admission without exporting or ingesting again. A file load is reused only
107
- * while a Runtime source snapshot still matches the earlier load's complete
107
+ * while the exporter's `revision` still matches the earlier load's complete
108
108
  * source revision; otherwise, or when every owner of the earlier admission has
109
109
  * released it, the load exports afresh. Failures are never reused.
110
110
  *
@@ -120,7 +120,7 @@ type ManagedGeoSpecNativeModelLoader = GeoSpecNativeModelLoader & {
120
120
  /**
121
121
  * Drain registered admissions, including additions while drainage awaits,
122
122
  * then release this scope's subjects (with a carrier: the previous scope's
123
- * subjects this scope did not load again) and owned Runtime clients.
123
+ * subjects this scope did not load again), then close every exporter it exported through.
124
124
  *
125
125
  * Await the intended complete load chain before final release, and await
126
126
  * this method before closing the caller-owned engine. Calls after it returns
@@ -135,7 +135,7 @@ type ManagedGeoSpecNativeModelLoader = GeoSpecNativeModelLoader & {
135
135
  * Create a native model loader that admits actual STEP/GLB bytes and retains
136
136
  * generation-checked handles until the owning runner finishes.
137
137
  *
138
- * @param defaults - Native engine, Runtime defaults, and optional source reader.
138
+ * @param defaults - Native engine, exporters, and optional source reader.
139
139
  * @returns A loader plus run-level cleanup operation.
140
140
  * @public
141
141
  */
@@ -1 +1 @@
1
- import{geoSpecAuthoredWorkUnitLimitProblem as e,resolveGeoSpecMaximumWorkUnitLimit as t}from"../engine/client.mjs";import{bindRawSubjectResidency as n}from"./subject.mjs";import{GeoSpecModelLoadError as r}from"./errors.mjs";import{resolveRuntimeExportIntent as i}from"./export-intent.mjs";import{assertRootedPath as a,isNotFoundError as o,joinRelativePath as s,sha256Bytes as c}from"@taucad/runtime/kernel";const l={canonicalProfile:`geospec-jcs-v1`,protocolVersion:3,registryVersion:5},u=new TextEncoder,d=new TextDecoder(`utf-8`,{fatal:!0}),f=new Set([`glb`,`step`,`stp`]),p=new WeakMap,m=16777216,h=e=>e instanceof Error&&`code`in e&&e.code===`limit-exceeded`&&`capacity`in e&&typeof e.capacity==`object`&&e.capacity!==null&&`unit`in e.capacity&&e.capacity.unit===`retained subjects`,g=(e,t)=>Object.assign(RangeError(e),{code:`limit-exceeded`,capacity:{code:`GEOSPEC_RESOURCE_LIMIT`,limitClass:`admission`,unit:`bytes`,...t,source:`host`}}),_=e=>{let t=p.get(e);if(t!==void 0)return t;let n=C(e.processRequest(x({...l,method:`initialize`,requestId:`configuration`})),`initialize response`),r=S(n.result,`initialize result`);if(n.requestId!==`configuration`||r.protocolVersion!==3||r.registryVersion!==5||r.canonicalProfile!==`geospec-jcs-v1`)throw TypeError(`Native GeoSpec residency requires a compatible initialize profile.`);let i=S(r.configuration,`initialize configuration`),a=S(i.binaryAdmissionLimits,`binary admission limits`),o=[a.maxSubjectBytes,a.maxTotalBinaryBytes].map(e=>{if(typeof e!=`number`||!Number.isSafeInteger(e)||e<=0)throw TypeError(`Native GeoSpec residency requires safe positive binary admission limits.`);return e}),s={inputs:new Map,resident:new Map,binaryLimit:Math.max(...o),binaryBytes:0,descriptorBytes:0};return p.set(e,s),s},v=e=>new r(e),y=e=>({code:e.code,severity:`error`,message:e.message,suggestion:e.suggestion,...e.details===void 0?{}:{details:e.details}}),b=e=>({code:e.code,severity:e.severity,message:e.message,suggestion:`Fix the model source or its Runtime export route, then retry the native run.`}),x=e=>u.encode(JSON.stringify(e)),S=(e,t)=>{if(typeof e!=`object`||!e||Array.isArray(e))throw TypeError(`Native GeoSpec returned a non-object ${t}.`);return e},C=(e,t)=>S(JSON.parse(d.decode(e)),t),w=/^(?:\/|[A-Za-z][A-Za-z0-9+.-]*:)/u,T=(e,t)=>e===void 0||w.test(t)?t:s(e,t),E=e=>{try{return a(e),!0}catch{return!1}},D=(e,t)=>`code`in e?{}:`source`in e?{...typeof e.source==`string`?{source:T(t,e.source)}:{},...e.resources===void 0?{}:{resources:e.resources.map(e=>typeof e.source==`string`?{...e,source:T(t,e.source)}:e)}}:{file:T(t,e.file)},O=(e,t)=>`${e.replace(/[/\\]+$/u,``)}/${t}`,k=e=>{let{path:t,projectPath:n,rootDir:r}=e;return y({code:`GEOSPEC_MODEL_SOURCE_NOT_FOUND`,message:`loadModel found no file '${t}'${r===void 0?``:` (rootDir '${r}')`} in the project root${n===void 0?``:` ${n}, looking for ${O(n,t)}`}.`,suggestion:`loadModel({ file }) resolves against the project root, the same root as every tool's targetFile: name the model by its path from that root, or pass rootDir with the project-relative folder it is in, as in loadModel({ file: 'main.ts', rootDir: 'parts/gear' }).`,details:{path:t,...r===void 0?{}:{rootDir:r},...n===void 0?{}:{projectRoot:n}}})},A=async(e,t,n={})=>{if(e instanceof Uint8Array)return Uint8Array.from(e);if(e instanceof ArrayBuffer)return Uint8Array.from(new Uint8Array(e));if(typeof Blob<`u`&&e instanceof Blob)return new Uint8Array(await e.arrayBuffer());if(t!==void 0)try{return await t(e)}catch(t){let{projectPath:r,rootDir:i}=n,a=typeof e==`string`&&r!==void 0&&!w.test(e);throw v([y({code:`GEOSPEC_NATIVE_SOURCE_READ_FAILED`,message:`The host source reader could not read ${typeof e==`string`?e:`this source`}${a?` at ${O(r,e)} in the project root ${r}${i===void 0?``:` (rootDir '${i}')`}`:``}: ${t instanceof Error?t.message:String(t)}`,suggestion:`Check that the source exists at its path from the project root, or pass rootDir with the project-relative folder it is in, and that it is readable, then retry the load.`,...typeof e==`string`?{details:{source:e,...i===void 0?{}:{rootDir:i},...a?{projectRoot:r}:{}}}:{}})])}throw v([y({code:`GEOSPEC_NATIVE_SOURCE_READER_UNAVAILABLE`,message:`The native model loader cannot read this source form without a host source reader.`,suggestion:`Pass in-memory bytes or configure readSource on createGeoSpecNativeModelLoader().`})])},j=e=>`code`in e?{files:e.code,entry:e.file}:{path:e.file},M=(e,t)=>{let n=e.format??t??`glb`;if(!f.has(n))throw v([y({code:`GEOSPEC_NATIVE_MODEL_FORMAT_UNSUPPORTED`,message:`The native model host does not admit '${n}' models.`,suggestion:`Use 'step', 'stp', or 'glb' for native model assertions.`,details:{format:n}})]);return n},N=(e,t)=>{let{routesFor:n,bestRouteFor:r}=e;if(typeof n==`function`)return n.call(e,t);let i=typeof r==`function`?r.call(e,t):void 0;return i===void 0?[]:[i]},P=async(e,t)=>{if(typeof e.describe==`function`)try{let{kernelId:n}=await e.describe({source:j(t)});return typeof n==`string`&&n.length>0?n:void 0}catch{return}},F=e=>{if(e===null||typeof e==`boolean`||typeof e==`string`)return JSON.stringify(e);if(typeof e==`number`)return Number.isFinite(e)?JSON.stringify(e):void 0;if(Array.isArray(e)){let t=e.map(e=>F(e));return t.includes(void 0)?void 0:`[${t.join(`,`)}]`}if(typeof e==`object`&&Object.getPrototypeOf(e)===Object.prototype){let t=Object.entries(e).filter(([,e])=>e!==void 0).sort(([e],[t])=>e<t?-1:1).map(([e,t])=>[e,F(t)]);return t.some(([,e])=>e===void 0)?void 0:`{${t.map(([e,t])=>`${JSON.stringify(e)}:${t}`).join(`,`)}}`}},I=e=>Array.isArray(e)&&e.length===3&&e.every(e=>typeof e==`number`&&Number.isFinite(e)),L=e=>{if(e===void 0)return;let t=typeof e==`object`&&e?e:{},{min:n,max:r}=t;return I(n)&&I(r)&&Object.keys(t).every(e=>e===`min`||e===`max`)&&n.every((e,t)=>e<r[t])?void 0:v([y({code:`GEOSPEC_MODEL_OPTION_INVALID`,message:`loadModel region must be { min: [x, y, z], max: [x, y, z] } in millimetres with every min axis below its max axis.`,suggestion:`Pass finite millimetre corners of the box to check, for example { min: [0, 0, 0], max: [40, 40, 60] }.`,details:{option:`region`,region:structuredClone(e)}})])},R=({min:e,max:t})=>({min:[e[0],e[1],e[2]],max:[t[0],t[1],t[2]]}),z=(e,t)=>{let n=t.sourceRevision?.files??Object.fromEntries(t.data.files.map(({path:e,sha256:t})=>[e,`sha256:${t}`]));return(t.sourceRevision?.entry??t.data.entryPath)===e.entry&&Object.entries(n).every(([t,n])=>n===`missing`||e.files[t]===n)&&Object.entries(e.files).every(([e,t])=>t===`missing`?n[e]===void 0||n[e]===`missing`:n[e]===t)},B=r=>{let a=0,s=t(r.maximumWorkUnitLimit),u=new Map,d=new Map,f=0,w=new Set,T=new Map,O=new Set,I=new Map,B=e=>(a+=1,`geospec-native-model:${e}:${a}`),V=e=>(e.sourceAdapters??r.sourceAdapters)?.find(t=>t.extensions.some(t=>e.file.endsWith(t))),H=async e=>{let t=e.runtime??r.runtime;if(typeof t==`function`){let e=I.get(t);e===void 0&&(e=t(),I.set(t,e));let n=await e;return O.add(n),n}if(t!==void 0)return t;let n=V(e);if(n!==void 0){let t=await n.createRuntime({file:e.file,...(e.projectPath??r.projectPath)===void 0?{}:{projectPath:e.projectPath??r.projectPath}});return O.add(t),t}throw v([y({code:`GEOSPEC_NATIVE_RUNTIME_UNAVAILABLE`,message:`No Tau Runtime is configured to export '${e.file}' for native GeoSpec.`,suggestion:`Pass a Runtime client/factory or a matching source adapter to the native runner.`,details:{file:e.file}})])},U=e=>{r.engine.releaseSubject(x({...l,method:`releaseSubject`,requestId:B(`release`),subjectHandle:e}))},W=(e,t)=>{let n=p.get(r.engine),i=n?.inputs.get(e);if(n!==void 0&&i!==void 0&&(i.cleanupPending?.(),delete i.cleanupPending,i.owners.has(t))){if(i.owners.size>1){i.owners.delete(t);return}i.handle!==void 0&&(U(i.handle),delete i.handle),i.owners.delete(t),n.resident.delete(e),n.inputs.delete(e),n.binaryBytes-=i.resources.reduce((e,t)=>e+t.byteLength,i.primary.byteLength),n.descriptorBytes-=i.request.byteLength}},G=e=>{for(let[t,n]of e.inputs)n.cleanupPending!==void 0&&(n.cleanupPending(),delete n.cleanupPending,delete n.handle,e.resident.delete(t))},K=()=>[...r.carried??[]].filter(([e])=>!u.has(e)),q=(e,t)=>{let n=e.format===`stp`?`step`:e.format,i=_(r.engine);G(i);let a=x({...l,method:`ingestSubject`,requestId:B(`ingest`),format:n,frame:{coordinateSystem:`z-up`,sourceUnit:n===`step`?`auto`:e.sourceUnit??`m`,outputUnit:`mm`},ingestOptions:e.ingestOptions??{},...e.diagnostics===void 0||e.diagnostics.length===0?{}:{diagnostics:e.diagnostics},primaryByteLength:e.primary.byteLength,resources:e.resources.map(({name:e,bytes:t})=>({name:e,byteLength:t.byteLength}))}),o=e.resources.reduce((e,{bytes:t})=>e+t.byteLength,e.primary.byteLength);if(!Number.isSafeInteger(o)||o>i.binaryLimit)throw g(`GeoSpec retained admission input exceeds its byte limit.`,{name:`maxTotalBinaryBytes`,limit:i.binaryLimit,required:o});if(a.byteLength>m)throw g(`GeoSpec retained admission input exceeds its byte limit.`,{name:`descriptorBytes`,limit:m,required:a.byteLength});let s=(e,t)=>e.length===t.length&&e.every((e,n)=>e===t[n]),c={...C(a,`admission request`),requestId:``},f=[...i.inputs.values()].find(t=>{let n={...C(t.request,`retained request`),requestId:``};return JSON.stringify(n)===JSON.stringify(c)&&s(t.primary,e.primary)&&t.resources.length===e.resources.length&&t.resources.every((t,n)=>s(t,e.resources[n].bytes))});if(f===void 0&&o>i.binaryLimit-i.binaryBytes)throw g(`GeoSpec live admission snapshots exceed their retained input byte limit.`,{name:`maxTotalBinaryBytes`,limit:i.binaryLimit,required:i.binaryBytes+o});if(f===void 0&&a.byteLength>m-i.descriptorBytes)throw g(`GeoSpec live admission snapshots exceed their retained input byte limit.`,{name:`descriptorBytes`,limit:m,required:i.descriptorBytes+a.byteLength});let p=f??{request:Uint8Array.from(a),primary:Uint8Array.from(e.primary),resources:e.resources.map(({bytes:e})=>Uint8Array.from(e)),owners:new Set},v=()=>r.engine.ingestSubject(a,e.primary,e.resources.map(({bytes:e})=>e)),y;try{y=v()}catch(e){let t=K();if(!h(e))throw e;let n=!1;for(let[e,a]of t){let t=i.inputs.get(e);if(t===void 0)U(a),n=!0;else{let i=t.owners.size===1&&t.handle!==void 0;W(e,r.carried),n||=i}r.carried?.delete(e)}if(!n){let t=i.resident.entries().next().value;if(t===void 0)throw e;U(t[1].handle),delete t[1].handle,i.resident.delete(t[0])}y=v()}let b=C(y,`admission response`),w=S(b.result,`admission result`),{subjectHash:T}=S(w.subject,`admitted subject`);if(typeof T!=`string`||!/^[0-9a-f]{64}$/u.test(T))throw TypeError(`Native GeoSpec admission did not return a valid subjectHash.`);let E=C(r.engine.subjectHandle(x({...l,method:`subjectHandle`,requestId:B(`handle`),subjectHash:T})),`subject-handle response`),D=S(E.result,`subject-handle result`).subjectHandle;if(D===void 0)throw TypeError(`Native GeoSpec did not return a subject handle.`);let O=i.inputs.get(T),k=O??p;O===void 0&&(i.inputs.set(T,k),i.binaryBytes+=o,i.descriptorBytes+=k.request.byteLength);for(let e of t)k.owners.add(e),d.set(e,T);return k.handle=D,i.resident.delete(T),i.resident.set(T,k),u.set(T,k),{subjectHash:T}},J=e=>{let t=u.get(e);if(t===void 0)throw TypeError(`This subject is not admitted by the active GeoSpec host.`);let n=_(r.engine);if(G(n),t.handle===void 0){let i=()=>r.engine.ingestSubject(t.request,t.primary,t.resources),a;try{a=i()}catch(e){let t=n.resident.entries().next().value;if(!h(e)||t===void 0)throw e;U(t[1].handle),delete t[1].handle,n.resident.delete(t[0]),a=i()}let o=()=>{let t=S(C(r.engine.subjectHandle(x({...l,method:`subjectHandle`,requestId:B(`restore-handle`),subjectHash:e})),`restored handle`).result,`restored handle result`),n=S(t.subjectHandle,`restored subject handle`);if(n.subjectHash!==e)throw TypeError(`Native GeoSpec restored handle changed its subject identity.`);return n};try{if(S(S(C(a,`restored admission`).result,`restored result`).subject,`restored subject`).subjectHash!==e)throw TypeError(`Native GeoSpec restored admission changed its subject identity.`);t.handle=o()}catch(e){throw t.cleanupPending=()=>{try{U(o())}catch(t){throw AggregateError([e,t],`Native GeoSpec restored admission failed and cleanup remains pending.`,{cause:e})}},t.cleanupPending(),delete t.cleanupPending,e}}n.resident.delete(e),n.resident.set(e,t)},Y=async e=>{if(r.readSource===void 0)return!1;try{return await r.readSource(e),!1}catch(e){return o(e)}},X=async(e,t)=>!(`code`in e)&&await Y(e.file)?[k({path:e.file,projectPath:r.projectPath,rootDir:e.rootDir})]:t.map(e=>b(e)),Z=async(e,t)=>{let n=M(e,r.format),i={projectPath:r.projectPath,rootDir:e.rootDir},a=await A(e.source,r.readSource,i),o=await Promise.all((e.resources??[]).map(async({name:e,source:t})=>({name:e,bytes:await A(t,r.readSource,i),...typeof t==`string`?{sourcePath:t}:{}}))),s=await Promise.all([{name:e.path??e.name??`primary`,bytes:a,...typeof e.source==`string`?{sourcePath:e.source}:{}},...o].map(async({name:e,bytes:t,sourcePath:n})=>({name:e,sha256:await c(t),byteLength:t.byteLength,...n===void 0?{}:{sourcePath:n}})));return{...q({format:n,primary:a,resources:o,...e.ingestOptions===void 0?{}:{ingestOptions:e.ingestOptions},...e.sourceUnit===void 0?{}:{sourceUnit:e.sourceUnit}},t),load:{loadId:``,status:`complete`,format:n,parameters:e.parameters??{},ingestOptions:e.ingestOptions??{},...typeof e.source==`string`?{sourcePath:e.source}:{},...e.rootDir===void 0?{}:{rootDir:e.rootDir},...e.workUnitLimit===void 0?{}:{workUnitLimit:e.workUnitLimit},artifacts:s}}},Q=async(e,t)=>{for(let t of[`sourceUnit`,`unit`,`scale`,`coordinateSystem`])if(t in e)throw v([y({code:`GEOSPEC_NATIVE_RUNTIME_FRAME_OVERRIDE`,message:`Native Runtime model loading rejects '${t}': the Runtime export intent owns the frame.`,suggestion:`Remove the frame override and let GeoSpec request canonical Z-up millimetre evidence.`,details:{key:t}})]);let n=M(e,r.format),a=n===`stp`?`step`:n,o=await H(e);await o.connect();let s=await P(o,e),l={runtime:o,format:a,...s===void 0?{}:{kernelId:s},...e.meshLinearTolerance===void 0?{}:{meshLinearTolerance:e.meshLinearTolerance},...e.meshAngularToleranceDegrees===void 0?{}:{meshAngularToleranceDegrees:e.meshAngularToleranceDegrees}},u=i(l);if(`success`in u)throw v(u.diagnostics);let d=e.region===void 0?void 0:R(e.region);if(d!==void 0){let t=N(o,a).filter(e=>s===void 0||e.kernelId===s);if(!t.some(e=>e.transcoderId===void 0&&`region`in(e.exportOptions?.schema.properties??{}))){let n=[...new Set(t.flatMap(e=>e.kernelId===void 0?[]:[e.kernelId]))];throw v([y({code:`GEOSPEC_MODEL_REGION_UNSUPPORTED`,message:`No direct ${a.toUpperCase()} export of this Runtime${n.length===0?``:` (${n.join(`, `)})`} declares a region option, so GeoSpec cannot crop '${e.file}' before admission.`,suggestion:`Load the whole model; if it exceeds a host limit, report the claim as not decided at this capacity. A region load needs a kernel whose GLB export crops, such as PicoVoxel, and only scopes a separate claim to that region.`,details:{file:e.file,format:a,region:d,kernelIds:n}})])}}let f={...structuredClone(u.options),...d===void 0?{}:{region:{min:[...d.min],max:[...d.max]}}},p=o.open({source:j(e),...e.parameters===void 0?{}:{parameters:e.parameters},watch:!1}),m=await(async()=>{try{return await p.export(a,{options:structuredClone(f)})}finally{p.close()}})();if(!m.success)throw v(await X(e,m.issues));if(d!==void 0&&!m.issues.some(e=>{let{details:t}=e,n=typeof t==`object`&&t&&`region`in t?t.region:void 0;return typeof n==`object`&&!!n&&F(n)===F({min:[...d.min],max:[...d.max]})}))throw v([y({code:`GEOSPEC_MODEL_REGION_NOT_HONORED`,message:`The Runtime export of '${e.file}' did not confirm the requested region crop, so its bytes may be the whole model.`,suggestion:`Load the whole model, or update the kernel so its export reports the region it cropped.`,details:{file:e.file,format:a,region:d}})]);let h=[...m.files],[g,..._]=h;if(g===void 0)throw v([y({code:`GEOSPEC_NATIVE_MODEL_EXPORT_EMPTY`,message:`The Tau Runtime exported no ${a.toUpperCase()} artifact for '${e.file}'.`,suggestion:`Check that the selected source exports geometry in the requested format.`,details:{file:e.file,format:a}})]);let x=i(l);if(`success`in x)throw v(x.diagnostics);let S=await Promise.all(h.map(async({name:e,bytes:t})=>({name:e,sha256:await c(t),byteLength:t.byteLength}))),C=m.sourceRevision===void 0?void 0:structuredClone(m.sourceRevision),w=C!==void 0&&/^sha256:[0-9a-f]{64}$/u.test(C.files[C.entry]??``)&&Object.values(C.files).every(e=>e===`missing`||/^sha256:[0-9a-f]{64}$/u.test(e));return{...q({format:a,primary:g.bytes,resources:_,sourceUnit:x.sourceUnit,diagnostics:m.issues.map(b),...e.ingestOptions===void 0?{}:{ingestOptions:e.ingestOptions}},t),load:{loadId:``,status:w?`complete`:`unavailable`,format:a,parameters:e.parameters??{},exportOptions:f,ingestOptions:e.ingestOptions??{},...C===void 0?{}:{sourceRevision:C},...`rootDir`in e&&e.rootDir!==void 0?{rootDir:e.rootDir}:{},...e.workUnitLimit===void 0?{}:{workUnitLimit:e.workUnitLimit},...d===void 0?{}:{region:d},artifacts:S}}},$=(e,t)=>{let n=p.get(r.engine)?.inputs.get(e);return n===void 0||n.owners.size===0?!1:(n.owners.add(t),d.set(t,e),u.set(e,n),!0)},ee=async(e,t)=>{let n=t.status===`complete`?t.sourceRevision:void 0;if(n===void 0)return!1;let r=await H(e);if(r.snapshotSource===void 0)return!1;try{let t=await r.snapshotSource({source:{path:e.file}});return t.success&&z(n,t)}catch{return!1}},te=async(e,t)=>{let n=e.runtime??r.runtime,i=`code`in e,a=i&&Object.values(e.code).every(e=>typeof e==`string`)?e.code:void 0,o=n===void 0||i&&a===void 0||[`sourceUnit`,`unit`,`scale`,`coordinateSystem`].some(t=>t in e)?void 0:F({file:e.file,code:a,projectPath:e.projectPath??r.projectPath,format:e.format??r.format??`glb`,meshLinearTolerance:e.meshLinearTolerance,meshAngularToleranceDegrees:e.meshAngularToleranceDegrees,parameters:e.parameters,ingestOptions:e.ingestOptions,region:e.region});if(n===void 0||o===void 0)return Q(e,new Set([t]));let s=T.get(n);s===void 0&&(s=new Map,T.set(n,s));let c=s.get(o);if(c!==void 0){c.owners?.add(t);let n=await c.pending;if((c.owners!==void 0||await ee(e,n.load))&&$(n.subjectHash,t)){let{workUnitLimit:t,rootDir:r,...i}=n.load;return{subjectHash:n.subjectHash,load:{...i,...`rootDir`in e&&e.rootDir!==void 0?{rootDir:e.rootDir}:{},...e.workUnitLimit===void 0?{}:{workUnitLimit:e.workUnitLimit},reused:!0}}}}let l=new Set([t]),u=Q(e,l),d={pending:u,...a===void 0?{}:{owners:l}};return s.set(o,d),u.then(void 0,()=>{s.delete(o)}),u};return Object.assign(t=>{let i={},a=B(`load`),o=`rootDir`in t?t.rootDir:void 0,c={...t,...`code`in t?{code:Object.fromEntries(Object.entries(t.code))}:{},...t.parameters===void 0?{}:{parameters:structuredClone(t.parameters)},...t.ingestOptions===void 0?{}:{ingestOptions:structuredClone(t.ingestOptions)},...`region`in t&&t.region!==void 0?{region:structuredClone(t.region)}:{},...typeof o==`string`&&E(o)?D(t,o):{}},l=t.format??r.format??`glb`,p=[`stepStreaming`,...`code`in t?[`rootDir`]:[],...t.mesh===!1&&(l===`step`||l===`stp`)?[]:[`mesh`],...`source`in t?[`meshLinearTolerance`,`meshAngularToleranceDegrees`,`region`,...l===`step`||l===`stp`?[`sourceUnit`]:[]]:[],...l===`step`||l===`stp`?[`region`]:[]].find(e=>e in t&&(e!==`region`&&e!==`rootDir`||t[e]!==void 0));if(p!==void 0)return Promise.reject(v([y({code:`GEOSPEC_MODEL_OPTION_UNSUPPORTED`,message:`This GeoSpec host cannot honor model option '${p}'.`,suggestion:`Remove this option or configure a host that supports its declared behavior.`,details:{option:p}})]));let m=e(t.workUnitLimit,`loadModel workUnitLimit`,s);if(m!==void 0)return Promise.reject(v([y({code:`GEOSPEC_MODEL_OPTION_INVALID`,message:m,suggestion:`Pass a positive integer workUnitLimit within the stated bound, or omit it for the engine default.`,details:{option:`workUnitLimit`}})]));let h=`source`in t?void 0:L(t.region);if(h!==void 0)return Promise.reject(h);if(o!==void 0&&!(typeof o==`string`&&E(o)))return Promise.reject(v([y({code:`GEOSPEC_MODEL_OPTION_INVALID`,message:`loadModel rootDir must be a project-relative folder in canonical form, such as 'parts/gear': no leading or trailing '/', and no '.' or '..' segments.`,suggestion:`Pass the folder the model is in, from the project root, as in rootDir: 'parts/gear', or name the file by its path from the project root.`,details:{option:`rootDir`,...typeof o==`string`?{rootDir:o}:{}}})]));let g=`source`in t?Z(c,new Set([i])):te(c,i),_=(async()=>{let e=await g,t={...e,...e.load===void 0?{}:{load:{...e.load,loadId:a}}},r=f,o=!1;return n(t,{ensureResident(){if(r!==f||!d.has(i))throw TypeError(`This subject is not admitted by the active GeoSpec host.`);J(e.subjectHash)},dispose(){if(!(o||!d.has(i))){o=!0;try{W(e.subjectHash,i),d.delete(i),[...d.values()].includes(e.subjectHash)||u.delete(e.subjectHash)}finally{o=!1}}}}),t})();return w.add(_),_},{async releaseAll(){do{let e=[...w];await Promise.allSettled(e);for(let t of e)w.delete(t)}while(w.size>0);let e=[],{carried:t}=r;if(f+=1,T.clear(),t!==void 0){for(let[n,i]of K())try{p.get(r.engine)?.inputs.has(n)?W(n,t):U(i),t.delete(n)}catch(t){e.push(t)}for(let[e,n]of u)n.handle===void 0?(n.owners.delete(t),t.delete(e)):(n.owners.add(t),t.set(e,n.handle))}for(let[t,n]of[...d].reverse())try{W(n,t),d.delete(t),[...d.values()].includes(n)||u.delete(n)}catch(t){e.push(t)}for(let t of O)try{t.shutdown?await t.shutdown():t.terminate()}catch(t){e.push(t)}if(O.clear(),I.clear(),e.length>0)throw AggregateError(e,`Native GeoSpec model cleanup failed.`)}})};export{B as createGeoSpecNativeModelLoader};
1
+ import{geoSpecAuthoredWorkUnitLimitProblem as e,resolveGeoSpecMaximumWorkUnitLimit as t}from"../engine/client.mjs";import{bindRawSubjectResidency as n}from"./subject.mjs";import{GeoSpecModelLoadError as r}from"./errors.mjs";import{assertRootedPath as i,isNotFoundError as a,joinRelativePath as o,sha256Bytes as s}from"@taucad/runtime/kernel";const c={canonicalProfile:`geospec-jcs-v1`,protocolVersion:3,registryVersion:5},l=new TextEncoder,u=new TextDecoder(`utf-8`,{fatal:!0}),d=new Set([`glb`,`step`,`stp`]),f=new WeakMap,p=16777216,m=e=>e instanceof Error&&`code`in e&&e.code===`limit-exceeded`&&`capacity`in e&&typeof e.capacity==`object`&&e.capacity!==null&&`unit`in e.capacity&&e.capacity.unit===`retained subjects`,h=(e,t)=>Object.assign(RangeError(e),{code:`limit-exceeded`,capacity:{code:`GEOSPEC_RESOURCE_LIMIT`,limitClass:`admission`,unit:`bytes`,...t,source:`host`}}),g=e=>{let t=f.get(e);if(t!==void 0)return t;let n=x(e.processRequest(y({...c,method:`initialize`,requestId:`configuration`})),`initialize response`),r=b(n.result,`initialize result`);if(n.requestId!==`configuration`||r.protocolVersion!==3||r.registryVersion!==5||r.canonicalProfile!==`geospec-jcs-v1`)throw TypeError(`Native GeoSpec residency requires a compatible initialize profile.`);let i=b(r.configuration,`initialize configuration`),a=b(i.binaryAdmissionLimits,`binary admission limits`),o=[a.maxSubjectBytes,a.maxTotalBinaryBytes].map(e=>{if(typeof e!=`number`||!Number.isSafeInteger(e)||e<=0)throw TypeError(`Native GeoSpec residency requires safe positive binary admission limits.`);return e}),s={inputs:new Map,resident:new Map,binaryLimit:Math.max(...o),binaryBytes:0,descriptorBytes:0};return f.set(e,s),s},_=e=>new r(e),v=e=>({code:e.code,severity:`error`,message:e.message,suggestion:e.suggestion,...e.details===void 0?{}:{details:e.details}}),y=e=>l.encode(JSON.stringify(e)),b=(e,t)=>{if(typeof e!=`object`||!e||Array.isArray(e))throw TypeError(`Native GeoSpec returned a non-object ${t}.`);return e},x=(e,t)=>b(JSON.parse(u.decode(e)),t),S=/^(?:\/|[A-Za-z][A-Za-z0-9+.-]*:)/u,C=(e,t)=>e===void 0||S.test(t)?t:o(e,t),w=e=>{try{return i(e),!0}catch{return!1}},T=(e,t)=>`code`in e?{}:`source`in e?{...typeof e.source==`string`?{source:C(t,e.source)}:{},...e.resources===void 0?{}:{resources:e.resources.map(e=>typeof e.source==`string`?{...e,source:C(t,e.source)}:e)}}:{file:C(t,e.file)},E=(e,t)=>`${e.replace(/[/\\]+$/u,``)}/${t}`,D=e=>{let{path:t,projectPath:n,rootDir:r}=e;return v({code:`GEOSPEC_MODEL_SOURCE_NOT_FOUND`,message:`loadModel found no file '${t}'${r===void 0?``:` (rootDir '${r}')`} in the project root${n===void 0?``:` ${n}, looking for ${E(n,t)}`}.`,suggestion:`loadModel({ file }) resolves against the project root, the same root as every tool's targetFile: name the model by its path from that root, or pass rootDir with the project-relative folder it is in, as in loadModel({ file: 'main.ts', rootDir: 'parts/gear' }).`,details:{path:t,...r===void 0?{}:{rootDir:r},...n===void 0?{}:{projectRoot:n}}})},O=async(e,t,n={})=>{if(e instanceof Uint8Array)return Uint8Array.from(e);if(e instanceof ArrayBuffer)return Uint8Array.from(new Uint8Array(e));if(typeof Blob<`u`&&e instanceof Blob)return new Uint8Array(await e.arrayBuffer());if(t!==void 0)try{return await t(e)}catch(t){let{projectPath:r,rootDir:i}=n,a=typeof e==`string`&&r!==void 0&&!S.test(e);throw _([v({code:`GEOSPEC_NATIVE_SOURCE_READ_FAILED`,message:`The host source reader could not read ${typeof e==`string`?e:`this source`}${a?` at ${E(r,e)} in the project root ${r}${i===void 0?``:` (rootDir '${i}')`}`:``}: ${t instanceof Error?t.message:String(t)}`,suggestion:`Check that the source exists at its path from the project root, or pass rootDir with the project-relative folder it is in, and that it is readable, then retry the load.`,...typeof e==`string`?{details:{source:e,...i===void 0?{}:{rootDir:i},...a?{projectRoot:r}:{}}}:{}})])}throw _([v({code:`GEOSPEC_NATIVE_SOURCE_READER_UNAVAILABLE`,message:`The native model loader cannot read this source form without a host source reader.`,suggestion:`Pass in-memory bytes or configure readSource on createGeoSpecNativeModelLoader().`})])},k=(e,t)=>{let n=t.slice(t.lastIndexOf(`/`)+1),r=n.lastIndexOf(`.`),i=r<=0?``:n.slice(r+1).toLowerCase();return e.extensions.some(e=>e===`*`||i!==``&&e.replace(/^\./u,``).toLowerCase()===i)},A=({exporter:e,file:t,capability:n,reason:r,details:i={}})=>_([v({code:`GEOSPEC_EXPORTER_UNSUPPORTED`,message:`Exporter '${e.id}' cannot export '${t}': ${r}`,suggestion:`Keep the claim and report it as unsupported by this exporter, or configure an exporter that declares the capability.`,details:{exporter:e.id,file:t,capability:n,...i}})]),j=(e,t,n)=>_([v({code:`GEOSPEC_EXPORTER_INVALID_ARTIFACT`,message:`Exporter '${e.id}' returned an artifact GeoSpec cannot admit for '${t}': ${n}`,suggestion:`Fix the exporter so it returns non-empty bytes in the requested format.`,details:{exporter:e.id,file:t}})]),M=/^(?:sha256:)?([0-9a-f]{64})$/u,N=(e,t)=>{if(t===void 0||t.length===0)return;let n={};for(let{path:e,sha256:r}of t){let t=M.exec(r)?.[1];n[e]=t===void 0?r:`sha256:${t}`}return{entry:e,files:n}},P=(e,t)=>{let n=e.format??t??`glb`;if(!d.has(n))throw _([v({code:`GEOSPEC_NATIVE_MODEL_FORMAT_UNSUPPORTED`,message:`The native model host does not admit '${n}' models.`,suggestion:`Use 'step', 'stp', or 'glb' for native model assertions.`,details:{format:n}})]);return n},F=e=>{if(e===null||typeof e==`boolean`||typeof e==`string`)return JSON.stringify(e);if(typeof e==`number`)return Number.isFinite(e)?JSON.stringify(e):void 0;if(Array.isArray(e)){let t=e.map(e=>F(e));return t.includes(void 0)?void 0:`[${t.join(`,`)}]`}if(typeof e==`object`&&Object.getPrototypeOf(e)===Object.prototype){let t=Object.entries(e).filter(([,e])=>e!==void 0).sort(([e],[t])=>e<t?-1:1).map(([e,t])=>[e,F(t)]);return t.some(([,e])=>e===void 0)?void 0:`{${t.map(([e,t])=>`${JSON.stringify(e)}:${t}`).join(`,`)}}`}},I=e=>Array.isArray(e)&&e.length===3&&e.every(e=>typeof e==`number`&&Number.isFinite(e)),L=e=>{if(e===void 0)return;let t=typeof e==`object`&&e?e:{},{min:n,max:r}=t;return I(n)&&I(r)&&Object.keys(t).every(e=>e===`min`||e===`max`)&&n.every((e,t)=>e<r[t])?void 0:_([v({code:`GEOSPEC_MODEL_OPTION_INVALID`,message:`loadModel region must be { min: [x, y, z], max: [x, y, z] } in millimetres with every min axis below its max axis.`,suggestion:`Pass finite millimetre corners of the box to check, for example { min: [0, 0, 0], max: [40, 40, 60] }.`,details:{option:`region`,region:structuredClone(e)}})])},R=({min:e,max:t})=>({min:[e[0],e[1],e[2]],max:[t[0],t[1],t[2]]}),z=(e,t)=>{let n=N(e.entry,t);if(n===void 0)return!1;let{files:r}=n;return Object.entries(r).every(([t,n])=>n===`missing`||e.files[t]===n)&&Object.entries(e.files).every(([e,t])=>t===`missing`?r[e]===void 0||r[e]===`missing`:r[e]===t)},B=i=>{let o=0,l=t(i.maximumWorkUnitLimit),u=new Map,d=new Map,S=0,C=new Set,E=new Map,M=new Set,I=e=>(o+=1,`geospec-native-model:${e}:${o}`),B=e=>{let t=i.exporters??[],n=t.find(t=>k(t,e.file));if(n!==void 0)return n;throw _([v({code:`GEOSPEC_EXPORTER_MISSING`,message:t.length===0?`No exporter is configured, so GeoSpec cannot export '${e.file}'.`:`No configured exporter claims '${e.file}', so GeoSpec cannot export it.`,suggestion:`Give the host an exporter whose extensions include this file's, or load STEP or GLB bytes directly.`,details:{file:e.file,exporters:t.map(({id:e})=>e)}})])},V=e=>{i.engine.releaseSubject(y({...c,method:`releaseSubject`,requestId:I(`release`),subjectHandle:e}))},H=(e,t)=>{let n=f.get(i.engine),r=n?.inputs.get(e);if(n!==void 0&&r!==void 0&&(r.cleanupPending?.(),delete r.cleanupPending,r.owners.has(t))){if(r.owners.size>1){r.owners.delete(t);return}r.handle!==void 0&&(V(r.handle),delete r.handle),r.owners.delete(t),n.resident.delete(e),n.inputs.delete(e),n.binaryBytes-=r.resources.reduce((e,t)=>e+t.byteLength,r.primary.byteLength),n.descriptorBytes-=r.request.byteLength}},U=e=>{for(let[t,n]of e.inputs)n.cleanupPending!==void 0&&(n.cleanupPending(),delete n.cleanupPending,delete n.handle,e.resident.delete(t))},W=()=>[...i.carried??[]].filter(([e])=>!u.has(e)),G=(e,t)=>{let n=e.format===`stp`?`step`:e.format,r=g(i.engine);U(r);let a=y({...c,method:`ingestSubject`,requestId:I(`ingest`),format:n,frame:{coordinateSystem:`z-up`,sourceUnit:n===`step`?`auto`:e.sourceUnit??`m`,outputUnit:`mm`},ingestOptions:e.ingestOptions??{},...e.diagnostics===void 0||e.diagnostics.length===0?{}:{diagnostics:e.diagnostics},primaryByteLength:e.primary.byteLength,resources:e.resources.map(({name:e,bytes:t})=>({name:e,byteLength:t.byteLength}))}),o=e.resources.reduce((e,{bytes:t})=>e+t.byteLength,e.primary.byteLength);if(!Number.isSafeInteger(o)||o>r.binaryLimit)throw h(`GeoSpec retained admission input exceeds its byte limit.`,{name:`maxTotalBinaryBytes`,limit:r.binaryLimit,required:o});if(a.byteLength>p)throw h(`GeoSpec retained admission input exceeds its byte limit.`,{name:`descriptorBytes`,limit:p,required:a.byteLength});let s=(e,t)=>e.length===t.length&&e.every((e,n)=>e===t[n]),l={...x(a,`admission request`),requestId:``},f=[...r.inputs.values()].find(t=>{let n={...x(t.request,`retained request`),requestId:``};return JSON.stringify(n)===JSON.stringify(l)&&s(t.primary,e.primary)&&t.resources.length===e.resources.length&&t.resources.every((t,n)=>s(t,e.resources[n].bytes))});if(f===void 0&&o>r.binaryLimit-r.binaryBytes)throw h(`GeoSpec live admission snapshots exceed their retained input byte limit.`,{name:`maxTotalBinaryBytes`,limit:r.binaryLimit,required:r.binaryBytes+o});if(f===void 0&&a.byteLength>p-r.descriptorBytes)throw h(`GeoSpec live admission snapshots exceed their retained input byte limit.`,{name:`descriptorBytes`,limit:p,required:r.descriptorBytes+a.byteLength});let _=f??{request:Uint8Array.from(a),primary:Uint8Array.from(e.primary),resources:e.resources.map(({bytes:e})=>Uint8Array.from(e)),owners:new Set},v=()=>i.engine.ingestSubject(a,e.primary,e.resources.map(({bytes:e})=>e)),S;try{S=v()}catch(e){let t=W();if(!m(e))throw e;let n=!1;for(let[e,a]of t){let t=r.inputs.get(e);if(t===void 0)V(a),n=!0;else{let r=t.owners.size===1&&t.handle!==void 0;H(e,i.carried),n||=r}i.carried?.delete(e)}if(!n){let t=r.resident.entries().next().value;if(t===void 0)throw e;V(t[1].handle),delete t[1].handle,r.resident.delete(t[0])}S=v()}let C=x(S,`admission response`),w=b(C.result,`admission result`),{subjectHash:T}=b(w.subject,`admitted subject`);if(typeof T!=`string`||!/^[0-9a-f]{64}$/u.test(T))throw TypeError(`Native GeoSpec admission did not return a valid subjectHash.`);let E=x(i.engine.subjectHandle(y({...c,method:`subjectHandle`,requestId:I(`handle`),subjectHash:T})),`subject-handle response`),D=b(E.result,`subject-handle result`).subjectHandle;if(D===void 0)throw TypeError(`Native GeoSpec did not return a subject handle.`);let O=r.inputs.get(T),k=O??_;O===void 0&&(r.inputs.set(T,k),r.binaryBytes+=o,r.descriptorBytes+=k.request.byteLength);for(let e of t)k.owners.add(e),d.set(e,T);return k.handle=D,r.resident.delete(T),r.resident.set(T,k),u.set(T,k),{subjectHash:T}},K=e=>{let t=u.get(e);if(t===void 0)throw TypeError(`This subject is not admitted by the active GeoSpec host.`);let n=g(i.engine);if(U(n),t.handle===void 0){let r=()=>i.engine.ingestSubject(t.request,t.primary,t.resources),a;try{a=r()}catch(e){let t=n.resident.entries().next().value;if(!m(e)||t===void 0)throw e;V(t[1].handle),delete t[1].handle,n.resident.delete(t[0]),a=r()}let o=()=>{let t=b(x(i.engine.subjectHandle(y({...c,method:`subjectHandle`,requestId:I(`restore-handle`),subjectHash:e})),`restored handle`).result,`restored handle result`),n=b(t.subjectHandle,`restored subject handle`);if(n.subjectHash!==e)throw TypeError(`Native GeoSpec restored handle changed its subject identity.`);return n};try{if(b(b(x(a,`restored admission`).result,`restored result`).subject,`restored subject`).subjectHash!==e)throw TypeError(`Native GeoSpec restored admission changed its subject identity.`);t.handle=o()}catch(e){throw t.cleanupPending=()=>{try{V(o())}catch(t){throw AggregateError([e,t],`Native GeoSpec restored admission failed and cleanup remains pending.`,{cause:e})}},t.cleanupPending(),delete t.cleanupPending,e}}n.resident.delete(e),n.resident.set(e,t)},q=async e=>{if(i.readSource===void 0)return!1;try{return await i.readSource(e),!1}catch(e){return a(e)}},J=async(e,t)=>!(`code`in e)&&await q(e.file)?_([D({path:e.file,projectPath:i.projectPath,rootDir:e.rootDir})]):t,Y=async(e,t)=>{let n=P(e,i.format),r={projectPath:i.projectPath,rootDir:e.rootDir},a=await O(e.source,i.readSource,r),o=await Promise.all((e.resources??[]).map(async({name:e,source:t})=>({name:e,bytes:await O(t,i.readSource,r),...typeof t==`string`?{sourcePath:t}:{}}))),c=await Promise.all([{name:e.path??e.name??`primary`,bytes:a,...typeof e.source==`string`?{sourcePath:e.source}:{}},...o].map(async({name:e,bytes:t,sourcePath:n})=>({name:e,sha256:await s(t),byteLength:t.byteLength,...n===void 0?{}:{sourcePath:n}})));return{...G({format:n,primary:a,resources:o,...e.ingestOptions===void 0?{}:{ingestOptions:e.ingestOptions},...e.sourceUnit===void 0?{}:{sourceUnit:e.sourceUnit}},t),load:{loadId:``,status:`complete`,format:n,parameters:e.parameters??{},ingestOptions:e.ingestOptions??{},...typeof e.source==`string`?{sourcePath:e.source}:{},...e.rootDir===void 0?{}:{rootDir:e.rootDir},...e.workUnitLimit===void 0?{}:{workUnitLimit:e.workUnitLimit},artifacts:c}}},X=async(e,t)=>{let{exporter:n,options:a,format:o}=e,{capabilities:c}=n;if(!c.formats.includes(o))throw A({exporter:n,file:a.file,capability:`formats`,reason:`it does not produce ${o.toUpperCase()}.`,details:{format:o,formats:[...c.formats]}});let l=`code`in a?a.code:void 0;if(l!==void 0&&c.inlineSources!==!0)throw A({exporter:n,file:a.file,capability:`inlineSources`,reason:`it does not accept inline sources.`});let u=a.parameters===void 0||Object.keys(a.parameters).length===0?void 0:a.parameters;if(u!==void 0&&c.parameters!==!0)throw A({exporter:n,file:a.file,capability:`parameters`,reason:`it does not accept parameters.`,details:{parameters:Object.keys(u)}});let d=a.region===void 0?void 0:R(a.region);if(d!==void 0&&c.region!==!0)throw A({exporter:n,file:a.file,capability:`region`,reason:`it does not crop to a region.`,details:{region:d}});let f=a.projectPath??i.projectPath,p=a.meshLinearTolerance===void 0&&a.meshAngularToleranceDegrees===void 0?void 0:{...a.meshLinearTolerance===void 0?{}:{linearTolerance:a.meshLinearTolerance},...a.meshAngularToleranceDegrees===void 0?{}:{angularToleranceDegrees:a.meshAngularToleranceDegrees}},m={file:a.file,format:o,...f===void 0?{}:{projectPath:f},...u===void 0?{}:{parameters:structuredClone(u)},...p===void 0?{}:{mesh:p},...d===void 0?{}:{region:R(d)},...l===void 0?{}:{inline:{...l}}},h;M.add(n);try{h=await n.export(m)}catch(e){throw await J(a,e instanceof r?e:_([v({code:`GEOSPEC_EXPORTER_FAILED`,message:`Exporter '${n.id}' failed to export '${a.file}': ${e instanceof Error?e.message:String(e)}`,suggestion:`Fix the model or the exporter, then rerun.`,details:{exporter:n.id,file:a.file,format:o}})]))}if(!(h.bytes instanceof Uint8Array)||h.bytes.byteLength===0)throw j(n,a.file,`its bytes are empty.`);if(h.format!==o)throw j(n,a.file,`it is ${String(h.format)}, not the requested ${o}.`);let g=(h.resources??[]).map(({name:e,bytes:t})=>({name:e,bytes:t})),y=await Promise.all([{name:`model.${o}`,bytes:h.bytes},...g].map(async({name:e,bytes:t})=>({name:e,sha256:await s(t),byteLength:t.byteLength}))),b=N(a.file,h.consumedSources),x=b!==void 0&&/^sha256:[0-9a-f]{64}$/u.test(b.files[b.entry]??``)&&Object.values(b.files).every(e=>e===`missing`||/^sha256:[0-9a-f]{64}$/u.test(e)),S=G({format:o,primary:h.bytes,resources:g,sourceUnit:h.sourceUnit??`mm`,...h.diagnostics===void 0?{}:{diagnostics:h.diagnostics},...a.ingestOptions===void 0?{}:{ingestOptions:a.ingestOptions}},t),C={exporter:n.id,...p===void 0?{}:{mesh:p},...d===void 0?{}:{region:{min:[...d.min],max:[...d.max]}},...h.exportOptions===void 0?{}:{options:structuredClone(h.exportOptions)}};return{...S,load:{loadId:``,status:x?`complete`:`unavailable`,format:o,parameters:a.parameters??{},exportOptions:C,ingestOptions:a.ingestOptions??{},...b===void 0?{}:{sourceRevision:b},...`rootDir`in a&&a.rootDir!==void 0?{rootDir:a.rootDir}:{},...a.workUnitLimit===void 0?{}:{workUnitLimit:a.workUnitLimit},...d===void 0?{}:{region:d},artifacts:y}}},Z=async(e,t)=>{for(let t of[`sourceUnit`,`unit`,`scale`,`coordinateSystem`])if(t in e)throw _([v({code:`GEOSPEC_NATIVE_RUNTIME_FRAME_OVERRIDE`,message:`Exported model loading rejects '${t}': the exporter owns the frame.`,suggestion:`Remove the frame override and let GeoSpec request canonical Z-up millimetre evidence.`,details:{key:t}})]);let n=P(e,i.format),r=n===`stp`?`step`:n;return X({exporter:B(e),options:e,format:r},t)},Q=(e,t)=>{let n=f.get(i.engine)?.inputs.get(e);return n===void 0||n.owners.size===0?!1:(n.owners.add(t),d.set(t,e),u.set(e,n),!0)},$=async(e,t,n)=>{let r=n.status===`complete`?n.sourceRevision:void 0;if(r===void 0||e.revision===void 0)return!1;let a=t.projectPath??i.projectPath;try{return z(r,await e.revision({file:t.file,...a===void 0?{}:{projectPath:a}}))}catch{return!1}},ee=async(e,t)=>{let n=i.exporters?.find(t=>k(t,e.file)),r=`code`in e,a=r&&Object.values(e.code).every(e=>typeof e==`string`)?e.code:void 0,o=n===void 0||r&&a===void 0||[`sourceUnit`,`unit`,`scale`,`coordinateSystem`].some(t=>t in e)?void 0:F({file:e.file,code:a,projectPath:e.projectPath??i.projectPath,format:e.format??i.format??`glb`,meshLinearTolerance:e.meshLinearTolerance,meshAngularToleranceDegrees:e.meshAngularToleranceDegrees,parameters:e.parameters,ingestOptions:e.ingestOptions,region:e.region});if(n===void 0||o===void 0)return Z(e,new Set([t]));let s=E.get(n);s===void 0&&(s=new Map,E.set(n,s));let c=s.get(o);if(c!==void 0){c.owners?.add(t);let r=await c.pending;if((c.owners!==void 0||await $(n,e,r.load))&&Q(r.subjectHash,t)){let{workUnitLimit:t,rootDir:n,...i}=r.load;return{subjectHash:r.subjectHash,load:{...i,...`rootDir`in e&&e.rootDir!==void 0?{rootDir:e.rootDir}:{},...e.workUnitLimit===void 0?{}:{workUnitLimit:e.workUnitLimit},reused:!0}}}}let l=new Set([t]),u=Z(e,l),d={pending:u,...a===void 0?{}:{owners:l}};return s.set(o,d),u.then(void 0,()=>{s.delete(o)}),u};return Object.assign(t=>{let r={},a=I(`load`),o=`rootDir`in t?t.rootDir:void 0,s={...t,...`code`in t?{code:Object.fromEntries(Object.entries(t.code))}:{},...t.parameters===void 0?{}:{parameters:structuredClone(t.parameters)},...t.ingestOptions===void 0?{}:{ingestOptions:structuredClone(t.ingestOptions)},...`region`in t&&t.region!==void 0?{region:structuredClone(t.region)}:{},...typeof o==`string`&&w(o)?T(t,o):{}},c=t.format??i.format??`glb`,f=[`stepStreaming`,...`code`in t?[`rootDir`]:[],...t.mesh===!1&&(c===`step`||c===`stp`)?[]:[`mesh`],...`source`in t?[`meshLinearTolerance`,`meshAngularToleranceDegrees`,`region`,...c===`step`||c===`stp`?[`sourceUnit`]:[]]:[],...c===`step`||c===`stp`?[`region`]:[]].find(e=>e in t&&(e!==`region`&&e!==`rootDir`||t[e]!==void 0));if(f!==void 0)return Promise.reject(_([v({code:`GEOSPEC_MODEL_OPTION_UNSUPPORTED`,message:`This GeoSpec host cannot honor model option '${f}'.`,suggestion:`Remove this option or configure a host that supports its declared behavior.`,details:{option:f}})]));let p=e(t.workUnitLimit,`loadModel workUnitLimit`,l);if(p!==void 0)return Promise.reject(_([v({code:`GEOSPEC_MODEL_OPTION_INVALID`,message:p,suggestion:`Pass a positive integer workUnitLimit within the stated bound, or omit it for the engine default.`,details:{option:`workUnitLimit`}})]));let m=`source`in t?void 0:L(t.region);if(m!==void 0)return Promise.reject(m);if(o!==void 0&&!(typeof o==`string`&&w(o)))return Promise.reject(_([v({code:`GEOSPEC_MODEL_OPTION_INVALID`,message:`loadModel rootDir must be a project-relative folder in canonical form, such as 'parts/gear': no leading or trailing '/', and no '.' or '..' segments.`,suggestion:`Pass the folder the model is in, from the project root, as in rootDir: 'parts/gear', or name the file by its path from the project root.`,details:{option:`rootDir`,...typeof o==`string`?{rootDir:o}:{}}})]));let h=`source`in t?Y(s,new Set([r])):ee(s,r),g=(async()=>{let e=await h,t={...e,...e.load===void 0?{}:{load:{...e.load,loadId:a}}},i=S,o=!1;return n(t,{ensureResident(){if(i!==S||!d.has(r))throw TypeError(`This subject is not admitted by the active GeoSpec host.`);K(e.subjectHash)},dispose(){if(!(o||!d.has(r))){o=!0;try{H(e.subjectHash,r),d.delete(r),[...d.values()].includes(e.subjectHash)||u.delete(e.subjectHash)}finally{o=!1}}}}),t})();return C.add(g),g},{async releaseAll(){do{let e=[...C];await Promise.allSettled(e);for(let t of e)C.delete(t)}while(C.size>0);let e=[],{carried:t}=i;if(S+=1,E.clear(),t!==void 0){for(let[n,r]of W())try{f.get(i.engine)?.inputs.has(n)?H(n,t):V(r),t.delete(n)}catch(t){e.push(t)}for(let[e,n]of u)n.handle===void 0?(n.owners.delete(t),t.delete(e)):(n.owners.add(t),t.set(e,n.handle))}for(let[t,n]of[...d].reverse())try{H(n,t),d.delete(t),[...d.values()].includes(n)||u.delete(n)}catch(t){e.push(t)}for(let t of M)try{await t.close?.()}catch(t){e.push(t)}if(M.clear(),e.length>0)throw AggregateError(e,`Native GeoSpec model cleanup failed.`)}})};export{B as createGeoSpecNativeModelLoader};
@@ -0,0 +1,31 @@
1
+ import { GeoSpecExporterCapabilities, GeoSpecModelExporter } from "../types.mjs";
2
+ //#region src/model/node/command-exporter.d.ts
3
+ /**
4
+ * Options for {@link commandExporter}.
5
+ *
6
+ * @public
7
+ */
8
+ type CommandExporterOptions = {
9
+ readonly id: string;
10
+ /** File extensions without the dot, or `'*'`. */
11
+ readonly extensions: readonly string[];
12
+ /** Executable and leading arguments, such as `['python', 'export.py']`. */
13
+ readonly command: readonly string[];
14
+ /** What the command can do. Protocol 1 carries no inline sources, so `inlineSources` must not be set. */
15
+ readonly capabilities: GeoSpecExporterCapabilities;
16
+ /** Working directory of the command; defaults to the request's project root. */
17
+ readonly cwd?: string;
18
+ /** Extra environment variables, merged over this process's. */
19
+ readonly env?: Readonly<Record<string, string>>;
20
+ };
21
+ /**
22
+ * Create a model exporter that runs a command speaking GeoSpec subprocess protocol 1.
23
+ *
24
+ * @param options - The exporter's identity, command and declared capabilities.
25
+ * @returns A {@link GeoSpecModelExporter}; each `export` call gets its own output directory.
26
+ * @throws TypeError when the options are incomplete or declare `inlineSources`.
27
+ * @public
28
+ */
29
+ declare const commandExporter: (options: CommandExporterOptions) => GeoSpecModelExporter;
30
+ //#endregion
31
+ export { CommandExporterOptions, commandExporter };