geospec 0.1.0-beta.6 → 0.1.0-beta.8

package/agent/doctrine.md

@@ -6,6 +6,7 @@ Write tests before implementation; assert deterministic, measurable properties.
 - Await `loadModel`, then assert synchronously with `expectGeo(model)`. The host supplies the compiled binding; authoring does not select an engine.
 - Await or return the complete model-load chain from the test callback; detached future loads are not part of a completed test.
 - Omit `parameters` for model-code defaults; use `{ file, parameters }` for variants. Loaded subjects are opaque.
+- `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.
 
 Canonical TypeScript authoring:
 
@@ -32,11 +33,25 @@ Every matcher takes one expectation object:
 ## Loads and budgets
 
 - 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.
-- `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`; raise the budget within the bound or simplify the model, and never treat the refusal as a pass.
+- `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.
 - `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.
-- A host or engine limit leaves a claim undecided, never false. Keep the model as designed: never coarsen, shrink or crop it to fit. Raise `workUnitLimit` or `testTimeout` within the host's maximum, which the host can raise, or report the claim as not decided at this capacity.
+- 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.
 - `toHaveCenterOfMass({ point, tolerance })` takes an exact point. Per-axis ranges such as `{ y: { greaterThan: 1 } }` are refused.
 
+## Ceilings
+
+Fixed in this release; design within them, and report a claim that meets one as not decided.
+
+| Ceiling                               | Value                | Where an agent meets it                                                                                                           |
+| ------------------------------------- | -------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
+| `maxSubjectBytes`, `maxResourceBytes` | 64 MiB each          | A mesh `loadModel({ file })` exports about 72 bytes per triangle, so admission refuses near 930,000 triangles (`resource-limit`). |
+| `maxTotalBinaryBytes`                 | 128 MiB              | All subjects of one load together.                                                                                                |
+| `maxTriangles`, `maxVertices`         | 4,000,000, 2,000,000 | A decoded mesh.                                                                                                                   |
+| `continuousEvidenceBytes`             | 32 MiB               | `toHaveNoComponentInterference` on a large assembly (`analysis-limit`).                                                           |
+| `workUnitLimit`                       | 512000000 at most    | Any claim; the only limit an argument raises.                                                                                     |
+
+Load `format: 'step'` only for the exact-BRep matchers above; every other matcher answers on the cheaper mesh.
+
 ## Coverage
 
 Bounds 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.

package/agent/geospec-authoring/SKILL.md

@@ -13,6 +13,7 @@ Write tests before implementation; assert deterministic, measurable properties.
 - Await `loadModel`, then assert synchronously with `expectGeo(model)`. The host supplies the compiled binding; authoring does not select an engine.
 - Await or return the complete model-load chain from the test callback; detached future loads are not part of a completed test.
 - Omit `parameters` for model-code defaults; use `{ file, parameters }` for variants. Loaded subjects are opaque.
+- `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.
 
 Canonical TypeScript authoring:
 
@@ -39,11 +40,25 @@ Every matcher takes one expectation object:
 ## Loads and budgets
 
 - 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.
-- `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`; raise the budget within the bound or simplify the model, and never treat the refusal as a pass.
+- `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.
 - `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.
-- A host or engine limit leaves a claim undecided, never false. Keep the model as designed: never coarsen, shrink or crop it to fit. Raise `workUnitLimit` or `testTimeout` within the host's maximum, which the host can raise, or report the claim as not decided at this capacity.
+- 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.
 - `toHaveCenterOfMass({ point, tolerance })` takes an exact point. Per-axis ranges such as `{ y: { greaterThan: 1 } }` are refused.
 
+## Ceilings
+
+Fixed in this release; design within them, and report a claim that meets one as not decided.
+
+| Ceiling                               | Value                | Where an agent meets it                                                                                                           |
+| ------------------------------------- | -------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
+| `maxSubjectBytes`, `maxResourceBytes` | 64 MiB each          | A mesh `loadModel({ file })` exports about 72 bytes per triangle, so admission refuses near 930,000 triangles (`resource-limit`). |
+| `maxTotalBinaryBytes`                 | 128 MiB              | All subjects of one load together.                                                                                                |
+| `maxTriangles`, `maxVertices`         | 4,000,000, 2,000,000 | A decoded mesh.                                                                                                                   |
+| `continuousEvidenceBytes`             | 32 MiB               | `toHaveNoComponentInterference` on a large assembly (`analysis-limit`).                                                           |
+| `workUnitLimit`                       | 512000000 at most    | Any claim; the only limit an argument raises.                                                                                     |
+
+Load `format: 'step'` only for the exact-BRep matchers above; every other matcher answers on the cheaper mesh.
+
 ## Coverage
 
 Bounds 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.
@@ -87,9 +102,11 @@ export declare function loadModel<Code extends Record<string, string> = Record<s
 
 // Options accepted by {@link import ('./load-model.js').loadModel}
 LoadModelOptions: LoadModelSourceOptions | LoadModelCodeOptions<Code> | LoadModelFileOptions
+  // Project-relative folder `file` resolves in, for a suite that loads from somewhere other than…
+  rootDir?: string
   // Geometry format to export
   format?: GeoSpecModelFormat
-  // Explicit parameters passed to the runtime
+  // Explicit parameters passed to the exporter
   parameters?: Record<string, unknown>
   // STEP reader strategy used for STEP exports
   stepStreaming?: StepStreamingMode
@@ -104,6 +121,18 @@ LoadModelOptions: LoadModelSourceOptions | LoadModelCodeOptions<Code> | LoadMode
 
 // Geometry formats accepted by {@link import ('./load-model.js').loadModel}
 GeoSpecModelFormat: MeshFileFormat | 'step' | 'stp'
+
+// GeoSpec test helper used inside VM-executed test modules
+export declare function it(name: string, function_: GeoSpecTestCallback): void;
+  skip(name: string, function_?: GeoSpecTestCallback): void;
+
+// GeoSpec suite helper used inside VM-executed test modules
+export declare function describe(name: string, function_: GeoSpecTestCallback): void;
+  skip(name: string, function_?: GeoSpecTestCallback): void;
+
+// Alias for {@link it}
+export declare function test(name: string, function_: GeoSpecTestCallback): void;
+  skip(name: string, function_?: GeoSpecTestCallback): void;
 ```
 
 ### Types
@@ -420,15 +449,6 @@ GeoSpecSpatialRelationshipExpectation: {
   reason?: string
 }
 
-// Shared scalar expectation used by geometry measurements
-GeoSpecNumericExpectation: number | {
-    value?: number;
-    greaterThan?: number;
-    greaterThanOrEqual?: number;
-    lessThan?: number;
-    lessThanOrEqual?: number;
-}
-
 // Diagnostic emitted by GeoSpec loaders, analyzers, and matchers
 GeometryDiagnostic: {
   code: KernelIssueCode | (string & {})
@@ -443,49 +463,29 @@ GeometryDiagnostic: {
   details?: unknown
 }
 
-// Shared scalar expectation used by geometry measurements
-GeoSpecNumericExpectation: number | {
-    value?: number;
-    greaterThan?: number;
-    greaterThanOrEqual?: number;
-    lessThan?: number;
-    lessThanOrEqual?: number;
-}
-
-// Shared scalar expectation used by geometry measurements
-GeoSpecNumericExpectation: number | {
-    value?: number;
-    greaterThan?: number;
-    greaterThanOrEqual?: number;
-    lessThan?: number;
-    lessThanOrEqual?: number;
-}
-
-// Shared scalar expectation used by geometry measurements
-GeoSpecNumericExpectation: number | {
-    value?: number;
-    greaterThan?: number;
-    greaterThanOrEqual?: number;
-    lessThan?: number;
-    lessThanOrEqual?: number;
-}
-
 // Point expectation accepted by center and feature matchers
 GeoSpecPointExpectation: Vec3 | GeoSpecAxisExpectation
 
-// Shared scalar expectation used by geometry measurements
-GeoSpecNumericExpectation: number | {
-    value?: number;
-    greaterThan?: number;
-    greaterThanOrEqual?: number;
-    lessThan?: number;
-    lessThanOrEqual?: number;
+// One void-continuity waypoint
+GeoSpecVoidWaypoint: Vec3 | {
+    occurrence: string;
+}
+
+// Direct geometry-source model load options
+LoadModelSourceOptions: {
+  // Source geometry format
+  format?: GeoSpecModelFormat
+  // Explicit parameters recorded in provenance
+  parameters?: Record<string, unknown>
+  // Whether STEP loading should also produce mesh evidence
+  mesh?: boolean
+  // … 10 more members in the API reference: source, resources, rootDir, path, name, sourceUnit, stepStreaming, meshLinearTolerance, meshAngularToleranceDegrees, workUnitLimit
 }
 ```
 
 ## API reference
 
-To read any other signature, grep the skill directory for the name followed by `(` (or the bare type name): each hit is the declaration line and names its file; read a few lines around it for overloads and parameter notes. `api-index.md` lists all 360 symbols by file.
+To 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.
 
 - `api-functions.md` — Functions
 - `api-constants.md` — Constants

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

@@ -1,6 +1,6 @@
 # geospec — Functions
 
-7 top-level symbols. Signatures are verbatim typescript.
+6 top-level symbols. Signatures are verbatim typescript.
 
 // GeoSpec suite helper used inside VM-executed test modules
 // describe (function)
@@ -40,18 +40,3 @@ export declare function createModelLoader(defaults: CreateModelLoaderOptions): M
 // loadModel (function)
 export declare function loadModel<Code extends Record<string, string> = Record<string, string>>(_options: LoadModelOptions<Code>): Promise<GeoSpecSubject>;
 //   _options: Source, code, or file model load options
-
-// resolveRuntimeExportIntent (function)
-export declare function resolveRuntimeExportIntent(options: {
-    runtime: GeoSpecRuntimeClient;
-    format: RuntimeBackedModelFormat;
-    meshLinearTolerance?: number;
-    meshAngularToleranceDegrees?: number;
-    /**
-     * The kernel that evaluates this source, when the host knows it. Routes are
-     * then chosen among that kernel's own, so a mesh-only kernel is told its
-     * BRep matchers are unsupported instead of being sent to another kernel's
-     * STEP route.
-     */
-    kernelId?: string;
-}): RuntimeExportIntent | RuntimeExportIntentFailure;