geospec 0.1.0-beta.2 → 0.1.0-beta.4

package/agent/doctrine.md

@@ -29,6 +29,14 @@ Every matcher takes one expectation object:
 - Wrong: `await expectGeo(model)…`. Correct: await `loadModel`, then assert synchronously.
 - 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`.
 
+## 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, 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.
+- `toHaveCenterOfMass({ point, tolerance })` takes an exact point. Per-axis ranges such as `{ y: { greaterThan: 1 } }` are refused.
+
 ## 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

@@ -36,6 +36,14 @@ Every matcher takes one expectation object:
 - Wrong: `await expectGeo(model)…`. Correct: await `loadModel`, then assert synchronously.
 - 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`.
 
+## 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, 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.
+- `toHaveCenterOfMass({ point, tolerance })` takes an exact point. Per-axis ranges such as `{ y: { greaterThan: 1 } }` are refused.
+
 ## 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.
@@ -61,13 +69,19 @@ The symbols real Tau models use most, as verbatim declarations. Anything not sho
 
 ```ts
 // Start a geometry assertion chain
-export declare function expectGeo(subject: GeoSpecSubject): GeoSpecMatcher;
+export declare function expectGeo(subject: GeoSpecSubject, options?: GeoSpecExpectOptions): GeoSpecMatcher;
 
 // A model admitted by one live GeoSpec host scope
 GeoSpecSubject: {
   readonly [subjectBrand]: true
 }
 
+// Per-chain options accepted by `expectGeo(subject, options)`
+GeoSpecExpectOptions: {
+  // Deterministic work-unit budget for every claim in this chain
+  readonly workUnitLimit?: number
+}
+
 // Load a CAD model into GeoSpec evidence
 export declare function loadModel<Code extends Record<string, string> = Record<string, string>>(_options: LoadModelOptions<Code>): Promise<GeoSpecSubject>;
 
@@ -85,6 +99,8 @@ LoadModelOptions: LoadModelSourceOptions | LoadModelCodeOptions<Code> | LoadMode
   meshLinearTolerance?: number
   // Angular tolerance in degrees used while meshing exact BRep evidence
   meshAngularToleranceDegrees?: number
+  // Default work-unit budget for every claim on this subject
+  workUnitLimit?: number
 
 // Geometry formats accepted by {@link import ('./load-model.js').loadModel}
 GeoSpecModelFormat: MeshFileFormat | 'step' | 'stp'
@@ -230,6 +246,7 @@ GeoSpecMassExpectation: {
 
 // Center-of-mass expectation accepted by `expectGeo(...).toHaveCenterOfMass(...)`
 GeoSpecCenterOfMassExpectation: {
+  // Exact expected point in millimetres
   point: GeoSpecPointExpectation
   tolerance?: number
 }
@@ -456,24 +473,6 @@ GeoSpecNumericExpectation: 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;
-}
-
-// 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;
@@ -486,7 +485,7 @@ GeoSpecNumericExpectation: number | {
 
 ## 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 345 symbols by file.
+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.
 
 - `api-functions.md` — Functions
 - `api-constants.md` — Constants

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

@@ -1,6 +1,16 @@
 # geospec — Constants
 
-1 top-level symbols. Signatures are verbatim typescript.
+4 top-level symbols. Signatures are verbatim typescript.
 
 // Every matcher name exposed by {@link expectGeo}, derived from the live matcher surface so it can never drift from the real implementation
 geoSpecMatcherNames: readonly string[]
+
+// The matchers mesh evidence answers, as the GeoSpec authoring skill lists them (`packages/geospec/agent/geospec-authoring/SKILL.md`)
+geoSpecMeshEvidenceMatchers: readonly ["toHaveBoundingBox", "toHaveVolume", "toHaveSurfaceArea", "toHaveConnectedComponents", "toBeWatertight"]
+
+// The claims a region-cropped subject answers
+// Remarks: Every other kind quantifies over the whole model (component counts, all-components interference, occurrences, watertightness, integrity, topology, diagnostics) or relates parts the crop may have cut, so a crop can neither prove nor disprove it.
+geoSpecRegionScopedKinds: ReadonlySet<GeoSpecAssertion['kind']>
+
+// Diagnostic code of a whole-model claim made on a region-cropped subject
+geoSpecRegionWholeModelClaimCode: "GEOSPEC_REGION_WHOLE_MODEL_CLAIM"

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

@@ -11,8 +11,9 @@ export declare function describe(name: string, function_: GeoSpecTestCallback):
 
 // Start a geometry assertion chain
 // expectGeo (function)
-export declare function expectGeo(subject: GeoSpecSubject): GeoSpecMatcher;
+export declare function expectGeo(subject: GeoSpecSubject, options?: GeoSpecExpectOptions): GeoSpecMatcher;
 //   subject: geometry subject under test
+//   options: Optional chain options, such as a larger `workUnitLimit` for a claim that refused with `MATCHER_TIMEOUT`
 
 // GeoSpec test helper used inside VM-executed test modules
 // it (function)
@@ -46,4 +47,11 @@ export declare function resolveRuntimeExportIntent(options: {
     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;

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

@@ -1,6 +1,6 @@
 # geospec API index
 
-geospec 0.1.0-beta.2 · 345 symbols · extracted by TypeScript 5.9.3.
+geospec 0.1.0-beta.4 · 360 symbols · extracted by TypeScript 5.9.3.
 
 Every symbol appears here exactly once. The heading above each block names the file with its signature; grep the skill directory for `name(` to land on the declaration directly.
 
@@ -20,13 +20,16 @@ resolveRuntimeExportIntent (function)
 ## Constants — `api-constants.md`
 
 geoSpecMatcherNames (constant) — Every matcher name exposed by {@link expectGeo}, derived from the…
+geoSpecMeshEvidenceMatchers (constant) — The matchers mesh evidence answers, as the GeoSpec authoring skill…
+geoSpecRegionScopedKinds (constant) — The claims a region-cropped subject answers
+geoSpecRegionWholeModelClaimCode (constant) — Diagnostic code of a whole-model claim made on a region-cropped…
 
 ## Types — `api-types.md`
 
 GeoSpecSubject (type) [1 members] — A model admitted by one live GeoSpec host scope
   GeoSpecSubject.[subjectBrand] (property)
 GeoSpecUnit (type) — Geometry units accepted at GeoSpec evidence-loading boundaries
-GeoSpecAssertion (type) [8 members] — Geometry assertion collected from a GeoSpec test module
+GeoSpecAssertion (type) [9 members] — Geometry assertion collected from a GeoSpec test module
   GeoSpecAssertion.kind (property) — Assertion kind
   GeoSpecAssertion.subject (property) — User-authored value passed to expectGeo()
   GeoSpecAssertion.expected (property) — Expected geometry condition
@@ -34,6 +37,7 @@ GeoSpecAssertion (type) [8 members] — Geometry assertion collected from a GeoS
   GeoSpecAssertion.diagnostics (property) — Structured diagnostics from matcher evaluation
   GeoSpecAssertion.report (property) — Exact compiled assertion report, including core-owned bytes and polarity
   GeoSpecAssertion.loadId (property) — The host load which admitted this assertion's subject
+  GeoSpecAssertion.region (property) — The crop this assertion's subject was loaded with
   GeoSpecAssertion.durationMs (property) — Wall-clock cost of matcher evaluation in milliseconds (R1
 GeoSpecAssemblyOccurrenceExpectation (type) [3 members] — Assembly occurrence rule accepted by `expectGeo(...).toHaveAssemblyOccurrences(...)`
   GeoSpecAssemblyOccurrenceExpectation.name (property)
@@ -53,7 +57,7 @@ GeoSpecBoundingBoxExpectation (type) [5 members] — Bounding-box expectation ac
   GeoSpecBoundingBoxExpectation.center (property)
   GeoSpecBoundingBoxExpectation.tolerance (property)
 GeoSpecCenterOfMassExpectation (type) [2 members] — Center-of-mass expectation accepted by `expectGeo(...).toHaveCenterOfMass(...)`
-  GeoSpecCenterOfMassExpectation.point (property)
+  GeoSpecCenterOfMassExpectation.point (property) — Exact expected point in millimetres
   GeoSpecCenterOfMassExpectation.tolerance (property)
 GeoSpecChamferFeatureExpectation (type) [3 members] — Chamfer-feature expectation accepted by `expectGeo(...).toHaveChamferFeature(...)`
   GeoSpecChamferFeatureExpectation.distance (property)
@@ -69,6 +73,8 @@ GeoSpecCylindricalFaceExpectation (type) [3 members] — Cylindrical-face expect
   GeoSpecCylindricalFaceExpectation.radius (property)
   GeoSpecCylindricalFaceExpectation.axis (property)
   GeoSpecCylindricalFaceExpectation.tolerance (property)
+GeoSpecExpectOptions (type) [1 members] — Per-chain options accepted by `expectGeo(subject, options)`
+  GeoSpecExpectOptions.workUnitLimit (property) — Deterministic work-unit budget for every claim in this chain
 GeoSpecComponentInterferenceAllowance (type) [5 members] — Intentional component interference allowance accepted by `expectGeo(...).toHaveNoComponentInterference(...)`
   GeoSpecComponentInterferenceAllowance.kind (property)
   GeoSpecComponentInterferenceAllowance.left (property)
@@ -300,6 +306,9 @@ CreateModelLoaderOptions (type) [10 members] — Defaults accepted by {@link imp
   CreateModelLoaderOptions.mesh (property) — Whether STEP loading should also produce mesh evidence
   CreateModelLoaderOptions.meshLinearTolerance (property) — Linear tolerance used while meshing exact BRep evidence
   CreateModelLoaderOptions.meshAngularToleranceDegrees (property) — Angular tolerance in degrees used while meshing exact BRep evidence
+GeoSpecLoadRegion (type) [2 members] — Axis-aligned crop box in canonical Z-up millimetres
+  GeoSpecLoadRegion.min (property)
+  GeoSpecLoadRegion.max (property)
 GeoSpecModelFormat (type) — Geometry formats accepted by {@link import ('./load-model.js').loadModel}
 GeoSpecModelLoader (type) — Function shape used by GeoSpec runners to provide model loading…
 ManagedGeoSpecModelLoader (type) [1 members] — A configured loader whose shared runtime can be released with…
@@ -312,7 +321,7 @@ GeoSpecRuntimeSourceAdapter (type) [3 members] — Explicit source adapter for f
   GeoSpecRuntimeSourceAdapter.id (property)
   GeoSpecRuntimeSourceAdapter.extensions (property)
   GeoSpecRuntimeSourceAdapter.createRuntime (method)
-LoadModelCodeOptions (type) [11 members] — Inline code-CAD model load options
+LoadModelCodeOptions (type) [13 members] — Inline code-CAD model load options
   LoadModelCodeOptions.code (property) — Source files keyed by project-relative path
   LoadModelCodeOptions.file (property) — Entry path to render from {@link code }
   LoadModelCodeOptions.format (property) — Geometry format to export
@@ -324,7 +333,9 @@ LoadModelCodeOptions (type) [11 members] — Inline code-CAD model load options
   LoadModelCodeOptions.mesh (property) — Whether STEP loading should also produce mesh evidence
   LoadModelCodeOptions.meshLinearTolerance (property) — Linear tolerance used while meshing exact BRep evidence
   LoadModelCodeOptions.meshAngularToleranceDegrees (property) — Angular tolerance in degrees used while meshing exact BRep evidence
-LoadModelFileOptions (type) [10 members] — Filesystem-backed model load options
+  LoadModelCodeOptions.workUnitLimit (property) — Default work-unit budget for every claim on this subject
+  LoadModelCodeOptions.region (property) — Axis-aligned millimetre box the kernel crops the model to before…
+LoadModelFileOptions (type) [12 members] — Filesystem-backed model load options
   LoadModelFileOptions.file (property) — Project-relative model file to render
   LoadModelFileOptions.projectPath (property) — Project root used by runtime integrations
   LoadModelFileOptions.format (property) — Geometry format to export
@@ -335,14 +346,17 @@ LoadModelFileOptions (type) [10 members] — Filesystem-backed model load option
   LoadModelFileOptions.mesh (property) — Whether STEP loading should also produce mesh evidence
   LoadModelFileOptions.meshLinearTolerance (property) — Linear tolerance used while meshing exact BRep evidence
   LoadModelFileOptions.meshAngularToleranceDegrees (property) — Angular tolerance in degrees used while meshing exact BRep evidence
-LoadModelOptions (type) [6 members] — Options accepted by {@link import ('./load-model.js').loadModel}
+  LoadModelFileOptions.workUnitLimit (property) — Default work-unit budget for every claim on this subject
+  LoadModelFileOptions.region (property) — Axis-aligned millimetre box the kernel crops the model to before…
+LoadModelOptions (type) [7 members] — Options accepted by {@link import ('./load-model.js').loadModel}
   LoadModelOptions.format (property) — Geometry format to export
   LoadModelOptions.parameters (property) — Explicit parameters passed to the runtime
   LoadModelOptions.stepStreaming (property) — STEP reader strategy used for STEP exports
   LoadModelOptions.mesh (property) — Whether STEP loading should also produce mesh evidence
   LoadModelOptions.meshLinearTolerance (property) — Linear tolerance used while meshing exact BRep evidence
   LoadModelOptions.meshAngularToleranceDegrees (property) — Angular tolerance in degrees used while meshing exact BRep evidence
-LoadModelSourceOptions (type) [11 members] — Direct geometry-source model load options
+  LoadModelOptions.workUnitLimit (property) — Default work-unit budget for every claim on this subject
+LoadModelSourceOptions (type) [12 members] — Direct geometry-source model load options
   LoadModelSourceOptions.source (property) — Geometry bytes, path, browser file/blob, or in-memory mesh buffer
   LoadModelSourceOptions.resources (property) — Named external resources consumed alongside the direct geometry bytes
   LoadModelSourceOptions.format (property) — Source geometry format
@@ -354,6 +368,7 @@ LoadModelSourceOptions (type) [11 members] — Direct geometry-source model load
   LoadModelSourceOptions.mesh (property) — Whether STEP loading should also produce mesh evidence
   LoadModelSourceOptions.meshLinearTolerance (property) — Linear tolerance used while meshing exact BRep evidence
   LoadModelSourceOptions.meshAngularToleranceDegrees (property) — Angular tolerance in degrees used while meshing exact BRep evidence
+  LoadModelSourceOptions.workUnitLimit (property) — Default work-unit budget for every claim on this subject
 
 ## Classes — `api-classes.md`
 

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

@@ -1,6 +1,6 @@
 # geospec — Types
 
-67 top-level symbols. Signatures are verbatim typescript.
+69 top-level symbols. Signatures are verbatim typescript.
 
 // A model admitted by one live GeoSpec host scope
 GeoSpecSubject: {
@@ -29,6 +29,11 @@ GeoSpecAssertion: {
     report?: GeoSpecCanonicalClaimReport;
     /** The host load which admitted this assertion's subject; independent of equal geometry hashes. */
     loadId?: string;
+    /**
+     * The crop this assertion's subject was loaded with. Present only for a region load: the verdict
+     * holds for this millimetre box, never for the whole model.
+     */
+    region?: GeoSpecLoadRegion;
     /** Wall-clock cost of matcher evaluation in milliseconds (R1: budgeted matchers only). */
     durationMs?: number;
 }
@@ -54,6 +59,9 @@ GeoSpecAssertion: {
   // The host load which admitted this assertion's subject
   loadId?: string
 
+  // The crop this assertion's subject was loaded with
+  region?: GeoSpecLoadRegion
+
   // Wall-clock cost of matcher evaluation in milliseconds (R1
   durationMs?: number
 
@@ -126,10 +134,12 @@ GeoSpecBoundingBoxExpectation: {
 
 // Center-of-mass expectation accepted by `expectGeo(...).toHaveCenterOfMass(...)`
 GeoSpecCenterOfMassExpectation: {
+    /** Exact expected point in millimetres; per-axis ranges such as `{ greaterThan }` are not supported. */
     point: GeoSpecPointExpectation;
     tolerance?: number;
 }
 
+  // Exact expected point in millimetres
   point: GeoSpecPointExpectation
 
   tolerance?: number
@@ -179,6 +189,20 @@ GeoSpecCylindricalFaceExpectation: {
 
   tolerance?: number
 
+// Per-chain options accepted by `expectGeo(subject, options)`
+GeoSpecExpectOptions: {
+    /**
+     * Deterministic work-unit budget for every claim in this chain: a positive integer no
+     * greater than the host's maximum (default `geoSpecMaximumWorkUnitLimit`, 512 000 000). Omitted uses the subject's
+     * `loadModel` budget, then the host's, then the engine default. Raise it to retry a
+     * `MATCHER_TIMEOUT` refusal whose `details.used` exceeded `details.limit`.
+     */
+    readonly workUnitLimit?: number;
+}
+
+  // Deterministic work-unit budget for every claim in this chain
+  readonly workUnitLimit?: number
+
 // Intentional component interference allowance accepted by `expectGeo(...).toHaveNoComponentInterference(...)`
 GeoSpecComponentInterferenceAllowance: {
     kind?: 'intentionalInterference';
@@ -1437,6 +1461,16 @@ CreateModelLoaderOptions: {
   // Angular tolerance in degrees used while meshing exact BRep evidence
   meshAngularToleranceDegrees?: number
 
+// Axis-aligned crop box in canonical Z-up millimetres
+GeoSpecLoadRegion: {
+    readonly min: readonly [number, number, number];
+    readonly max: readonly [number, number, number];
+}
+
+  readonly min: readonly [number, number, number]
+
+  readonly max: readonly [number, number, number]
+
 // Geometry formats accepted by {@link import ('./load-model.js').loadModel}
 GeoSpecModelFormat: MeshFileFormat | 'step' | 'stp'
 
@@ -1452,8 +1486,8 @@ ManagedGeoSpecModelLoader: GeoSpecModelLoader & {
   dispose(): Promise<void>;
 
 // Runtime client surface consumed by `geospec/model`
-// Remarks: GeoSpec accepts concrete Tau runtime clients from multiple call sites but only needs connection lifecycle and request-scoped documents. Keep this shape small so typed runtime clients do not have to widen their full generic method surface to GeoSpec's testing DSL. A client with `shutdown` is awaited through it when GeoSpec releases an owned runtime, so its host resources are closed before the caller (for example a worker thread) exits.
-GeoSpecRuntimeClient: Pick<RuntimeClient, 'connect' | 'terminate'> & Partial<Pick<RuntimeClient, 'shutdown'>> & {
+// Remarks: GeoSpec accepts concrete Tau runtime clients from multiple call sites but only needs connection lifecycle and request-scoped documents. Keep this shape small so typed runtime clients do not have to widen their full generic method surface to GeoSpec's testing DSL. A client with `shutdown` is awaited through it when GeoSpec releases an owned runtime, so its host resources are closed before the caller (for example a worker thread) exits. A client with `snapshotSource` lets one run reuse an identical file load after confirming that the source closure it exported is unchanged.
+GeoSpecRuntimeClient: Pick<RuntimeClient, 'connect' | 'terminate'> & Partial<Pick<RuntimeClient, 'shutdown' | 'snapshotSource' | 'describe'>> & {
     open: (input: Pick<Parameters<RuntimeClient['open']>[0], 'source' | 'parameters' | 'stage' | 'watch' | 'signal'>) => Pick<ReturnType<RuntimeClient['open']>, 'export' | 'close'>;
     on?(event: 'telemetry', handler: (batch: {
         readonly entries: ReadonlyArray<{
@@ -1524,6 +1558,21 @@ LoadModelCodeOptions: {
     meshLinearTolerance?: number;
     /** Angular tolerance in degrees used while meshing exact BRep evidence. */
     meshAngularToleranceDegrees?: number;
+    /**
+     * Default work-unit budget for every claim on this subject: a positive integer no greater than
+     * the host's maximum (default `geoSpecMaximumWorkUnitLimit`, 512 000 000). `expectGeo(subject, { workUnitLimit })` overrides
+     * it per chain. Recorded in the load evidence; it never changes the exported or admitted bytes.
+     */
+    workUnitLimit?: number;
+    /**
+     * Axis-aligned millimetre box the kernel crops the model to before export, so a large mesh model
+     * can be checked region by region. Only kernels whose direct GLB export declares a `region` option
+     * honor it; any other kernel, a STEP load or a crop the kernel does not confirm refuses with a typed
+     * diagnostic instead of loading the whole model. The cropped subject is a different subject: its
+     * admission carries the kernel's crop notice and its load evidence records `region`, so a claim on
+     * it never stands for the whole model.
+     */
+    region?: GeoSpecLoadRegion;
 }
 
   // Source files keyed by project-relative path
@@ -1559,6 +1608,12 @@ LoadModelCodeOptions: {
   // Angular tolerance in degrees used while meshing exact BRep evidence
   meshAngularToleranceDegrees?: number
 
+  // Default work-unit budget for every claim on this subject
+  workUnitLimit?: number
+
+  // Axis-aligned millimetre box the kernel crops the model to before export, so a large mesh model can be checked region by region
+  region?: GeoSpecLoadRegion
+
 // Filesystem-backed model load options
 LoadModelFileOptions: {
     /** Project-relative model file to render. */
@@ -1581,6 +1636,21 @@ LoadModelFileOptions: {
     meshLinearTolerance?: number;
     /** Angular tolerance in degrees used while meshing exact BRep evidence. */
     meshAngularToleranceDegrees?: number;
+    /**
+     * Default work-unit budget for every claim on this subject: a positive integer no greater than
+     * the host's maximum (default `geoSpecMaximumWorkUnitLimit`, 512 000 000). `expectGeo(subject, { workUnitLimit })` overrides
+     * it per chain. Recorded in the load evidence; it never changes the exported or admitted bytes.
+     */
+    workUnitLimit?: number;
+    /**
+     * Axis-aligned millimetre box the kernel crops the model to before export, so a large mesh model
+     * can be checked region by region. Only kernels whose direct GLB export declares a `region` option
+     * honor it; any other kernel, a STEP load or a crop the kernel does not confirm refuses with a typed
+     * diagnostic instead of loading the whole model. The cropped subject is a different subject: its
+     * admission carries the kernel's crop notice and its load evidence records `region`, so a claim on
+     * it never stands for the whole model.
+     */
+    region?: GeoSpecLoadRegion;
 }
 
   // Project-relative model file to render
@@ -1613,6 +1683,12 @@ LoadModelFileOptions: {
   // Angular tolerance in degrees used while meshing exact BRep evidence
   meshAngularToleranceDegrees?: number
 
+  // Default work-unit budget for every claim on this subject
+  workUnitLimit?: number
+
+  // Axis-aligned millimetre box the kernel crops the model to before export, so a large mesh model can be checked region by region
+  region?: GeoSpecLoadRegion
+
 // Options accepted by {@link import ('./load-model.js').loadModel}
 LoadModelOptions: LoadModelSourceOptions | LoadModelCodeOptions<Code> | LoadModelFileOptions
 
@@ -1634,6 +1710,9 @@ LoadModelOptions: LoadModelSourceOptions | LoadModelCodeOptions<Code> | LoadMode
   // Angular tolerance in degrees used while meshing exact BRep evidence
   meshAngularToleranceDegrees?: number
 
+  // Default work-unit budget for every claim on this subject
+  workUnitLimit?: number
+
 // Direct geometry-source model load options
 LoadModelSourceOptions: {
     /** Geometry bytes, path, browser file/blob, or in-memory mesh buffer. */
@@ -1661,6 +1740,12 @@ LoadModelSourceOptions: {
     meshLinearTolerance?: number;
     /** Angular tolerance in degrees used while meshing exact BRep evidence. */
     meshAngularToleranceDegrees?: number;
+    /**
+     * Default work-unit budget for every claim on this subject: a positive integer no greater than
+     * the host's maximum (default `geoSpecMaximumWorkUnitLimit`, 512 000 000). `expectGeo(subject, { workUnitLimit })` overrides
+     * it per chain. Recorded in the load evidence; it never changes the exported or admitted bytes.
+     */
+    workUnitLimit?: number;
 }
 
   // Geometry bytes, path, browser file/blob, or in-memory mesh buffer
@@ -1698,3 +1783,6 @@ LoadModelSourceOptions: {
 
   // Angular tolerance in degrees used while meshing exact BRep evidence
   meshAngularToleranceDegrees?: number
+
+  // Default work-unit budget for every claim on this subject
+  workUnitLimit?: number

package/agent/geospec-authoring/public-api-constants.md

@@ -1,6 +1,6 @@
 # geospec — Constants
 
-4 top-level symbols. Signatures are verbatim typescript.
+9 top-level symbols. Signatures are verbatim typescript.
 
 // Every matcher name exposed by {@link expectGeo}, derived from the live matcher surface so it can never drift from the real implementation
 geoSpecMatcherNames: readonly string[]
@@ -12,8 +12,40 @@ geoSpecMatcherDescriptors: Readonly<{
     } : GeoSpecMatcherDescriptor;
 }>
 
+// The matchers mesh evidence answers, as the GeoSpec authoring skill lists them (`packages/geospec/agent/geospec-authoring/SKILL.md`)
+geoSpecMeshEvidenceMatchers: readonly ["toHaveBoundingBox", "toHaveVolume", "toHaveSurfaceArea", "toHaveConnectedComponents", "toBeWatertight"]
+
+// The claims a region-cropped subject answers
+// Remarks: Every other kind quantifies over the whole model (component counts, all-components interference, occurrences, watertightness, integrity, topology, diagnostics) or relates parts the crop may have cut, so a crop can neither prove nor disprove it.
+geoSpecRegionScopedKinds: ReadonlySet<GeoSpecAssertion['kind']>
+
+// Diagnostic code of a whole-model claim made on a region-cropped subject
+geoSpecRegionWholeModelClaimCode: "GEOSPEC_REGION_WHOLE_MODEL_CLAIM"
+
 // Directories skipped by recursive GeoSpec discovery unless callers provide their own ignored-directory list
 defaultGeoSpecIgnoredDirectories: readonly [".git", "node_modules", "dist", "coverage", ".tau/cache", ".tau/artifacts", ".tau/transcripts"]
 
 // Default file globs used by GeoSpec test discovery
 defaultGeoSpecInclude: readonly ["**/*.geospec.{ts,js}"]
+
+// Codes for GeoSpec wall-clock timeouts, one per bound
+geoSpecTimeoutCode: {
+    /** A test's async body outlived `testTimeout` / `--test-timeout`. */
+    readonly test: "GEOSPEC_TEST_TIMEOUT";
+    /** A pool shard outlived the non-verdict `--shard-timeout` watchdog. */
+    readonly shard: "GEOSPEC_SHARD_TIMEOUT";
+    /** A whole run outlived its host run budget. */
+    readonly run: "GEOSPEC_RUN_TIMEOUT";
+}
+
+  // A test's async body outlived `testTimeout` / `--test-timeout`
+  readonly test: "GEOSPEC_TEST_TIMEOUT"
+
+  // A pool shard outlived the non-verdict `--shard-timeout` watchdog
+  readonly shard: "GEOSPEC_SHARD_TIMEOUT"
+
+  // A whole run outlived its host run budget
+  readonly run: "GEOSPEC_RUN_TIMEOUT"
+
+// Default largest work-unit budget a spec may author through `loadModel` or `expectGeo` options
+geoSpecMaximumWorkUnitLimit: 512000000

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

@@ -1,6 +1,6 @@
 # geospec — Functions
 
-34 top-level symbols. Signatures are verbatim typescript.
+36 top-level symbols. Signatures are verbatim typescript.
 
 // GeoSpec suite helper used inside VM-executed test modules
 // describe (function)
@@ -11,8 +11,9 @@ export declare function describe(name: string, function_: GeoSpecTestCallback):
 
 // Start a geometry assertion chain
 // expectGeo (function)
-export declare function expectGeo(subject: GeoSpecSubject): GeoSpecMatcher;
+export declare function expectGeo(subject: GeoSpecSubject, options?: GeoSpecExpectOptions): GeoSpecMatcher;
 //   subject: geometry subject under test
+//   options: Optional chain options, such as a larger `workUnitLimit` for a claim that refused with `MATCHER_TIMEOUT`
 
 // GeoSpec test helper used inside VM-executed test modules
 // it (function)
@@ -72,6 +73,13 @@ export declare function resolveRuntimeExportIntent(options: {
     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;
 
 // clearCollectorGlobals (function)
@@ -125,6 +133,11 @@ export declare function isGeoSpecTestFile(path: string): boolean;
 export declare function runGeoSpecModule(options: RunGeoSpecModuleOptions): Promise<GeoSpecRunResult>;
 //   options: filesystem and test entry path
 
+// Whether a diagnostic or issue code belongs to the GeoSpec timeout family
+// isGeoSpecTimeoutCode (function)
+export declare function isGeoSpecTimeoutCode(code: string): code is GeoSpecTimeoutCode;
+//   code: Any diagnostic or issue code
+
 // Compose compiled assertion and model bindings with the SDK's serial lifecycle
 // createNativeGeoSpecRunner (function)
 export declare function createNativeGeoSpecRunner(options: GeoSpecNativeRunnerOptions): GeoSpecRunner;
@@ -168,6 +181,12 @@ export declare function createGeoSpecMatcherMethods<Result>(options: {
 export declare function evaluateGeoSpecNativeQuery(options: GeoSpecNativeQueryOptions): GeoSpecCanonicalClaimReport;
 //   options: Query identity, subject and authored payload
 
+// Resolve a host's largest authored work-unit budget
+// Throws: TypeError when the configured maximum is not a positive safe integer.
+// resolveGeoSpecMaximumWorkUnitLimit (function)
+export declare function resolveGeoSpecMaximumWorkUnitLimit(maximum?: number): number;
+//   maximum: The host's configured maximum, when it sets one
+
 // Create Vitest matchers over an existing runner-independent client
 // createGeoSpecVitestAdapter (function)
 export declare function createGeoSpecVitestAdapter(client: GeoSpecAssertionClient): GeoSpecVitestAdapter;