geospec 0.0.0 → 0.1.0-beta.3

package/dist/runner/worker/index.d.mts

@@ -0,0 +1,4 @@
+import { createNoMatchingGeoSpecTestsIssue } from "./no-matching-tests-issue.mjs";
+import { GeoSpecPoolHostMessage, GeoSpecPoolShard, GeoSpecPoolWorkerHandle, GeoSpecPoolWorkerMessage } from "../pool/pool-messages.mjs";
+import { GeoSpecForensicEvent, GeoSpecRunner, GeoSpecRunnerEvent, GeoSpecRunnerFileResult, GeoSpecRunnerOptions, GeoSpecRunnerResult, GeoSpecRunnerRunOptions } from "./runner-types.mjs";
+export { type GeoSpecForensicEvent, type GeoSpecPoolHostMessage, type GeoSpecPoolShard, type GeoSpecPoolWorkerHandle, type GeoSpecPoolWorkerMessage, type GeoSpecRunner, type GeoSpecRunnerEvent, type GeoSpecRunnerFileResult, type GeoSpecRunnerOptions, type GeoSpecRunnerResult, type GeoSpecRunnerRunOptions, createNoMatchingGeoSpecTestsIssue };

package/dist/runner/worker/index.mjs

@@ -0,0 +1 @@
+import{createNoMatchingGeoSpecTestsIssue as e}from"./no-matching-tests-issue.mjs";export{e as createNoMatchingGeoSpecTestsIssue};

package/dist/runner/worker/no-matching-tests-issue.d.mts

@@ -0,0 +1,12 @@
+import { VmIssue } from "@taucad/esbuild/vm";
+//#region src/runner/worker/no-matching-tests-issue.d.ts
+/**
+ * Create a run-level issue when filters select no tests.
+ *
+ * @returns A structured VM issue for empty GeoSpec filter selections.
+ *
+ * @public
+ */
+declare const createNoMatchingGeoSpecTestsIssue: () => VmIssue;
+//#endregion
+export { createNoMatchingGeoSpecTestsIssue };

package/dist/runner/worker/no-matching-tests-issue.mjs

@@ -0,0 +1 @@
+const e=()=>({code:`NO_MATCHING_GEOSPEC_TESTS`,message:`No matching GeoSpec tests were selected by the supplied filters.`,severity:`error`,type:`runtime`});export{e as createNoMatchingGeoSpecTestsIssue};

package/dist/runner/worker/runner-types.d.mts

@@ -0,0 +1,167 @@
+import { ManagedGeoSpecNativeModelLoader } from "../../model/native-model-loader.mjs";
+import { GeoSpecRunResult, GeoSpecTestAccounting, GeoSpecTestCase, RunGeoSpecModuleOptions } from "../types.mjs";
+import { VmFileSystem, VmIssue } from "@taucad/esbuild/vm";
+//#region src/runner/worker/runner-types.d.ts
+/**
+ * One GeoSpec test file executed by a worker-style runner.
+ *
+ * @public
+ */
+type GeoSpecRunnerFileResult = {
+  /** Absolute or project-relative GeoSpec test file path supplied to the runner. */
+  file: string;
+  /** Low-level module execution result for this file. */
+  result: GeoSpecRunResult;
+  /** Wall-clock cost of executing this file, in milliseconds (R1). */
+  durationMs?: number;
+  /** First deterministic model-load cache key observed in this file (R9 affinity telemetry). */
+  primaryLoadKey?: string;
+  /** Executing worker's isolate-resident memory at file completion, in bytes (R15 memory-class telemetry). */
+  workerMemoryBytes?: number;
+};
+/**
+ * Aggregate result returned by GeoSpec worker-style runners.
+ *
+ * @public
+ */
+type GeoSpecRunnerResult = {
+  /** True when no files or tests failed and at least one test was selected. */
+  success: boolean;
+  /** Number of non-skipped tests that passed. */
+  passed: number;
+  /** Number of file-level or test-level failures. */
+  failed: number;
+  /** Number of collected tests after filters were applied. */
+  selectedTests: number;
+  /** Per-file module execution results. */
+  files: GeoSpecRunnerFileResult[];
+  /** Run-level issues such as aborts or empty filter selections. */
+  issues?: VmIssue[];
+  /** Wall-clock cost of the whole run, in milliseconds (R1). */
+  durationMs?: number;
+  /** Complete requested-file accounting; discovery may remain unknown in unstarted or broken modules. */
+  accounting?: GeoSpecRunnerAccounting;
+  /** Coherence of the consumed source graphs, not a geometry verdict. */
+  lineageStatus?: 'complete' | 'unavailable' | 'mixed';
+};
+/** File and observed-test accounting for a worker run. @public */
+type GeoSpecRunnerAccounting = GeoSpecTestAccounting & {
+  requestedFiles: readonly string[];
+  completedFiles: readonly string[];
+  notRunFiles: readonly string[];
+  discoveryComplete: boolean;
+  cancelled: boolean;
+  bailed: boolean;
+};
+/** Identity of a test that has started but not settled. @public */
+type GeoSpecRunnerTestRef = {
+  readonly suite: readonly string[];
+  readonly name: string;
+  readonly ordinal?: number;
+};
+/**
+ * Lifecycle event emitted by GeoSpec worker-style runners. Test events are
+ * emitted by in-process runners; a pool reports per file.
+ *
+ * @public
+ */
+type GeoSpecRunnerEvent = {
+  type: 'run-start';
+  files: readonly string[];
+} | {
+  type: 'file-start';
+  file: string;
+} | {
+  type: 'test-start';
+  file: string;
+  test: GeoSpecRunnerTestRef;
+} | {
+  type: 'test-complete';
+  file: string;
+  test: GeoSpecTestCase;
+} | {
+  type: 'file-complete';
+  file: string;
+  result: GeoSpecRunResult;
+  durationMs?: number;
+  primaryLoadKey?: string;
+  workerMemoryBytes?: number;
+} | {
+  type: 'run-complete';
+  result: GeoSpecRunnerResult;
+} | GeoSpecForensicEvent | {
+  type: 'abort';
+  reason?: string;
+} | {
+  type: 'close';
+};
+/** One structured forensic measurement emitted by a runner. @public */
+type GeoSpecForensicEvent = {
+  type: 'forensic';
+  name: string;
+  value: number;
+  unit: 'milliseconds' | 'count';
+  shardId?: number;
+};
+/**
+ * Options accepted by a GeoSpec worker-style runner run.
+ *
+ * @public
+ */
+type GeoSpecRunnerRunOptions = {
+  /** GeoSpec test files to execute. Files run serially by default. */
+  files: readonly string[];
+  /** JavaScript regular expression matched against full `suite > test` names. */
+  testNamePattern?: string | RegExp;
+  /** Timeout for each async test callback, in milliseconds. */
+  testTimeout?: number;
+  /** Non-verdict matcher wall backstop. Milliseconds. */
+  matcherWallBackstop?: number;
+  /**
+   * Engine work-unit budget for this run's claims, replacing the runner's
+   * `nativeAssertions.workUnitLimit`. A `loadModel` or `expectGeo` budget still
+   * wins for its own claims.
+   */
+  workUnitLimit?: number;
+  /** Emit structured forensic measurements for this run. */
+  forensic?: boolean;
+  /**
+   * Stop after the first failing file (R1). Interactive fail-fast only —
+   * never the default for reward runs, which want the complete red set.
+   */
+  bail?: boolean;
+};
+/**
+ * Shared options for GeoSpec runner factories.
+ *
+ * @public
+ */
+type GeoSpecRunnerOptions = {
+  /** Filesystem containing the project and test modules. */
+  filesystem: VmFileSystem;
+  /** Protocol-3 assertion client shared by every authored assertion and model admission. */
+  nativeAssertions: RunGeoSpecModuleOptions['nativeAssertions'];
+  /** Managed native model loader released after each settled run. */
+  nativeModelLoader?: ManagedGeoSpecNativeModelLoader;
+  /** Additional in-memory modules made available to the VM. */
+  builtinModules?: RunGeoSpecModuleOptions['builtinModules'];
+};
+/**
+ * Public GeoSpec runner lifecycle surface.
+ *
+ * @public
+ */
+type GeoSpecRunner = {
+  /** Execute GeoSpec files and return a compact aggregate result. */
+  run(options: GeoSpecRunnerRunOptions): Promise<GeoSpecRunnerResult>;
+  /** Subscribe to one lifecycle event type. */
+  on<Type extends GeoSpecRunnerEvent['type']>(event: Type, handler: (event: Extract<GeoSpecRunnerEvent, {
+    type: Type;
+  }>) => void): () => void;
+  /** Request cooperative abort before the next file starts. */
+  abort(reason?: string): void;
+  /** Close the runner and release owned resources. */
+  close(): Promise<void>;
+};
+//#endregion
+export { GeoSpecForensicEvent, GeoSpecRunner, GeoSpecRunnerAccounting, GeoSpecRunnerEvent, GeoSpecRunnerFileResult, GeoSpecRunnerOptions, GeoSpecRunnerResult, GeoSpecRunnerRunOptions, GeoSpecRunnerTestRef };

package/dist/runner/worker/serial-runner.mjs

@@ -0,0 +1 @@
+import{runGeoSpecModule as e}from"../run-geospec-module.mjs";import{createNoMatchingGeoSpecTestsIssue as t}from"./no-matching-tests-issue.mjs";const n=()=>({code:`GEOSPEC_RUNNER_CLOSED`,message:`GeoSpec runner is closed.`,severity:`error`,type:`runtime`}),r=()=>({code:`GEOSPEC_RUNNER_ACTIVE`,message:`GeoSpec runner already has an active run.`,severity:`error`,type:`runtime`}),i=e=>({code:`GEOSPEC_RUNNER_ABORTED`,message:e?`GeoSpec run aborted: ${e}`:`GeoSpec run aborted.`,severity:`error`,type:`runtime`}),a=e=>({code:`GEOSPEC_RUNNER_BAILED`,message:`GeoSpec run stopped after first failure (--bail): ${e}. Remaining files were not executed.`,severity:`error`,type:`runtime`}),o=e=>{let t=0,n=0;for(let r of e)r.status!==`skipped`&&(r.status===`failed`?n+=1:r.status===`passed`&&(t+=1));return{passed:t,failed:n}},s=s=>{let c={closed:!1},l=new Set,u,d,f=new Map,p=e=>{for(let t of l)t(e)},m=()=>c.aborted,h=e=>({requestedFiles:[...e],completedFiles:[],notRunFiles:[...e],discoveryComplete:!1,discovered:0,selected:0,completed:0,passed:0,failed:0,unsupported:0,inconclusive:0,skipped:0,notRun:0,cancelled:!1,bailed:!1}),g=(e,t)=>({success:!1,passed:0,failed:1,selectedTests:0,files:[],issues:[e],accounting:h(t),lineageStatus:`unavailable`}),_=async n=>{let r=[...n.files],c=performance.now();p({type:`run-start`,files:r});let l=!1,u=async()=>{l||(l=!0,await s.nativeModelLoader?.releaseAll())},d=0,g=0,_=0,v=[],y=[],b=h(r),x=!0,S=`complete`,C=new Map;try{for(let t of r){let c=m();if(c!==void 0){let e=i(c);y.push(e),g+=1,p({type:`abort`,reason:c}),b.cancelled=!0,x=!1;break}p({type:`file-start`,file:t});let l=performance.now(),u=await e({filesystem:s.filesystem,entryPath:t,testNamePattern:n.testNamePattern,testTimeout:n.testTimeout,matcherWallBackstop:n.matcherWallBackstop,forensic:n.forensic,onTestEvent:e=>{p(e.type===`test-start`?{type:`test-start`,file:t,test:{suite:[...e.test.suite],name:e.test.name,...e.test.ordinal===void 0?{}:{ordinal:e.test.ordinal}}}:{type:`test-complete`,file:t,test:e.test})},bundleCache:f,nativeAssertions:n.workUnitLimit===void 0?s.nativeAssertions:{...s.nativeAssertions,workUnitLimit:n.workUnitLimit},...s.nativeModelLoader?{nativeModelLoader:s.nativeModelLoader}:{},...s.builtinModules?{builtinModules:s.builtinModules}:{}}).catch(e=>({success:!1,issues:[{code:`GEOSPEC_MODULE_INTERRUPTED`,message:e instanceof Error?e.message:String(e),severity:`error`,type:`runtime`}]})),h=performance.now()-l;p({type:`file-complete`,file:t,result:u,durationMs:h}),v.push({file:t,result:u,durationMs:h}),b.completedFiles=v.map(e=>e.file),b.notRunFiles=r.slice(v.length),x&&=u.success&&u.passed,u.lineage===void 0||u.lineage.status===`unavailable`?S!==`mixed`&&(S=`unavailable`):u.lineage.status===`mixed`&&(S=`mixed`);let w=u.lineage?.loads.flatMap(e=>{let{evidence:t}=e,n=t?.artifacts[0];return t?.exportOptions===void 0?[...(t?.artifacts??[]).flatMap(e=>e.sourcePath===void 0?[]:[{[e.sourcePath]:`sha256:${e.sha256}`}]),...t?.sourcePath===void 0||n===void 0?[]:[{[t.sourcePath]:`sha256:${n.sha256}`}]]:[]})??[];for(let e of[...u.lineage?.modules.map(e=>e.files)??[],...w,...u.lineage?.loads.map(e=>e.evidence?.sourceRevision?.files??{})??[]])for(let[t,n]of Object.entries(e))C.has(t)&&C.get(t)!==n&&(S=`mixed`),C.set(t,n);if(u.accounting!==void 0)for(let e of[`discovered`,`selected`,`completed`,`passed`,`failed`,`unsupported`,`inconclusive`,`skipped`,`notRun`])b[e]+=u.accounting[e];if(u.success){_+=u.tests.length;let e=o(u.tests);d+=e.passed,g+=e.failed}else g+=1;if(n.bail===!0&&(!x||g>0)){y.push(a(t)),b.bailed=!0;break}}_===0&&g===0&&(y.push(t()),g+=1);try{await u()}catch(e){y.push({code:`GEOSPEC_NATIVE_CLEANUP_FAILED`,message:e instanceof Error?e.message:String(e),severity:`error`,type:`runtime`}),x=!1}b.discoveryComplete=b.notRunFiles.length===0&&v.every(e=>e.result.success&&e.result.accounting!==void 0);let l={success:x&&S===`complete`&&g===0&&y.length===0,passed:d,failed:g,selectedTests:_,files:v,...y.length>0?{issues:y}:{},durationMs:performance.now()-c,accounting:b,lineageStatus:S};return p({type:`run-complete`,result:l}),l}finally{await u()}};return{async run(e){if(new Set(e.files).size!==e.files.length)return g({code:`GEOSPEC_DUPLICATE_FILES`,message:`GeoSpec requested files must be unique.`,severity:`error`,type:`runtime`},e.files);if(c.closed)return g(n(),e.files);if(u!==void 0)return g(r(),e.files);delete c.aborted;let t=()=>void 0,i=new Promise(e=>{t=e});u=i;try{return await _(e)}finally{t(),u===i&&(u=void 0)}},on(e,t){let n=n=>{n.type===e&&t(n)};return l.add(n),()=>l.delete(n)},abort(e){c.aborted=e??`requested`},async close(){d===void 0&&(c.closed=!0,c.aborted??=`runner closed`,d=(async()=>{await u,f.clear(),p({type:`close`})})()),await d}}};export{o as countRunnerTests,s as createSerialGeoSpecRunner};

package/dist/selector/types.d.mts

@@ -0,0 +1,271 @@
+import { Vec3 } from "../mesh/types.mjs";
+//#region src/selector/types.d.ts
+/**
+ * Surface classification carried by selector face facts, matching the
+ * verification kernel's `faceFacts` payload vocabulary.
+ *
+ * @public
+ */
+type SelectorSurfaceType = 'plane' | 'cylinder' | 'cone' | 'sphere' | 'torus' | 'bspline' | 'other';
+/**
+ * Inclusive numeric band. A bare number matches within the linear tolerance.
+ *
+ * @public
+ */
+type NumericRange = number | {
+  min?: number;
+  max?: number;
+};
+/**
+ * Cartesian coordinate record used by coordinate-band (`near`) predicates.
+ *
+ * @public
+ */
+type Vec3Record = {
+  x: number;
+  y: number;
+  z: number;
+};
+/**
+ * Cardinality expectation for a selector resolution (master catalog G7).
+ * `'one'` is the default for relationship endpoints; `'many'` for groups.
+ *
+ * @public
+ */
+type Cardinality = 'one' | 'many' | {
+  exactly: number;
+} | {
+  atLeast: number;
+};
+/**
+ * Direction predicate with optional angular tolerance in degrees.
+ *
+ * @public
+ */
+type DirectionPredicate = {
+  direction: Vec3;
+  angularToleranceDegrees?: number;
+};
+/**
+ * Ray probe predicate (world-space origin and direction, millimetres).
+ *
+ * @public
+ */
+type RayPredicate = {
+  origin: Vec3;
+  direction: Vec3;
+};
+/**
+ * Face query predicates (master catalog G1/G2): geometric fact predicates,
+ * world-space probes, scoping, ordering with deterministic pick, and set
+ * algebra. All tolerances default to the shared tolerance contract.
+ *
+ * @public
+ */
+type FaceQuery = {
+  surfaceType?: SelectorSurfaceType;
+  /** Face normal parallelism (planar faces). */
+  normal?: DirectionPredicate;
+  /** Rotation-axis parallelism (cylindrical/conical faces). */
+  axis?: DirectionPredicate;
+  radius?: NumericRange;
+  area?: NumericRange;
+  /** Plane offset band: signed distance of the plane from the origin. */
+  offset?: NumericRange;
+  /** Centroid coordinate bands, per-axis. */
+  near?: Partial<Vec3Record> & {
+    tolerance?: number;
+  };
+  /** Probe: point lying on the face surface (bounds + analytic residual). */
+  containsPoint?: Vec3;
+  /** Probe: face whose centroid is nearest to the point; ties are ambiguous. */
+  nearestTo?: Vec3;
+  /** Probe: first face hit by the ray (analytic plane/cylinder only in V1). */
+  hitByRay?: RayPredicate;
+  /** Restrict candidates to entities resolved by another selector. */
+  within?: GeometrySelector;
+  /** Deterministic ordering; `offsetAlong` projects centroids on `along`. */
+  orderBy?: 'area' | 'radius' | 'offsetAlong';
+  /** Projection direction for `orderBy: 'offsetAlong'`. */
+  along?: Vec3;
+  /** Deterministic pick after ordering: `'first' | 'last'` or 0-based index. */
+  pick?: 'first' | 'last' | number;
+  allOf?: FaceQuery[];
+  anyOf?: FaceQuery[];
+  not?: FaceQuery;
+};
+/**
+ * Axis query predicates over cylindrical/conical face facts.
+ *
+ * @public
+ */
+type AxisQuery = {
+  /** Axis direction parallelism. */
+  axis?: DirectionPredicate;
+  radius?: NumericRange;
+  near?: Partial<Vec3Record> & {
+    tolerance?: number;
+  };
+  containsPoint?: Vec3;
+  nearestTo?: Vec3;
+  within?: GeometrySelector;
+  orderBy?: 'radius' | 'offsetAlong';
+  along?: Vec3;
+  pick?: 'first' | 'last' | number;
+  allOf?: AxisQuery[];
+  anyOf?: AxisQuery[];
+  not?: AxisQuery;
+};
+/**
+ * Plane query predicates over planar face facts.
+ *
+ * @public
+ */
+type PlaneQuery = {
+  normal?: DirectionPredicate;
+  offset?: NumericRange;
+  area?: NumericRange;
+  near?: Partial<Vec3Record> & {
+    tolerance?: number;
+  };
+  containsPoint?: Vec3;
+  nearestTo?: Vec3;
+  within?: GeometrySelector;
+  orderBy?: 'area' | 'offsetAlong';
+  along?: Vec3;
+  pick?: 'first' | 'last' | number;
+  allOf?: PlaneQuery[];
+  anyOf?: PlaneQuery[];
+  not?: PlaneQuery;
+};
+/**
+ * Body query predicates over available source facts. The STEP index currently
+ * exposes per-occurrence solid aggregates. Qualified mesh Bodies are material
+ * roots, including their cavities; disconnected roots and cavity islands stay
+ * separate. Mesh measure, probe and ordering predicates without the required
+ * facts refuse, including inside boolean queries.
+ *
+ * @public
+ */
+type BodyQuery = {
+  area?: NumericRange;
+  near?: Partial<Vec3Record> & {
+    tolerance?: number;
+  };
+  nearestTo?: Vec3;
+  within?: GeometrySelector;
+  orderBy?: 'area' | 'offsetAlong';
+  along?: Vec3;
+  pick?: 'first' | 'last' | number;
+  allOf?: BodyQuery[];
+  anyOf?: BodyQuery[];
+  not?: BodyQuery;
+};
+/**
+ * Occurrence selector: a placed instance in the assembly tree.
+ *
+ * @public
+ */
+type OccurrenceSelector = {
+  kind: 'occurrence';
+  /** Product or instance name to match. */
+  name?: string | RegExp;
+  /** Occurrence path (dot-joined instance segments, root omitted) to match. */
+  path?: string | RegExp;
+  expect?: Cardinality;
+};
+/**
+ * Body selector over source-backed solid evidence. Qualified mesh input exposes
+ * one material root with its cavities; the STEP index currently exposes one
+ * solid aggregate per occurrence. These are not interchangeable body counts.
+ *
+ * @public
+ */
+type BodySelector = {
+  kind: 'body';
+  /** STEP occurrence scope, or the exact retained mesh primitive label including any ordinal suffix. */
+  of?: string | RegExp;
+  query?: BodyQuery;
+  expect?: Cardinality;
+};
+/**
+ * Face selector resolved via query/probe predicates.
+ *
+ * @public
+ */
+type FaceSelector = {
+  kind: 'face';
+  of?: string | RegExp;
+  query?: FaceQuery;
+  expect?: Cardinality;
+};
+/**
+ * Axis selector resolved from cylindrical/conical face facts.
+ *
+ * @public
+ */
+type AxisSelector = {
+  kind: 'axis';
+  of?: string | RegExp;
+  query?: AxisQuery;
+  expect?: Cardinality;
+};
+/**
+ * Plane selector resolved from planar face facts.
+ *
+ * @public
+ */
+type PlaneSelector = {
+  kind: 'plane';
+  of?: string | RegExp;
+  query?: PlaneQuery;
+  expect?: Cardinality;
+};
+/**
+ * Datum selector: a named coordinate frame authored as a native AP242 datum
+ * placement.
+ *
+ * @public
+ */
+type DatumSelector = {
+  kind: 'datum';
+  /** Full datum name, or part-relative name when `of` scopes an occurrence. */
+  name: string;
+  of?: string | RegExp;
+  expect?: Cardinality;
+};
+/**
+ * Interface selector: an authored named interface transported as a STEP
+ * `SHAPE_ASPECT` subshape name — the production-preferred selector.
+ *
+ * @public
+ */
+type InterfaceSelector = {
+  kind: 'interface';
+  /** Full interface name, or part-relative name when `of` scopes an occurrence. */
+  name: string;
+  of?: string | RegExp;
+  expect?: Cardinality;
+};
+/**
+ * Group selector: an ordered shared-name family (`bore[1]`…`bore[N]`).
+ *
+ * @public
+ */
+type GroupSelector = {
+  kind: 'group';
+  /** Full group prefix, or part-relative prefix when `of` scopes an occurrence. */
+  name: string;
+  of?: string | RegExp;
+  expect?: Cardinality;
+};
+/**
+ * The V1 geometry selector union (D4 scope). Strings are shorthand: authored
+ * paths (`'block.deck.left'`, `'headL.boltHole[*]'`) or snapshot topology
+ * refs (`'#o1.2.f7'`, always `stability: 'derived-ordinal'`).
+ *
+ * @public
+ */
+type GeometrySelector = string | OccurrenceSelector | BodySelector | FaceSelector | AxisSelector | PlaneSelector | DatumSelector | InterfaceSelector | GroupSelector;
+//#endregion
+export { AxisQuery, AxisSelector, BodyQuery, BodySelector, Cardinality, DatumSelector, DirectionPredicate, FaceQuery, FaceSelector, GeometrySelector, GroupSelector, InterfaceSelector, NumericRange, OccurrenceSelector, PlaneQuery, PlaneSelector, RayPredicate, SelectorSurfaceType, Vec3Record };

package/dist/step/types.d.mts

@@ -0,0 +1,134 @@
+//#region src/step/types.d.ts
+/**
+ * STEP source and AP242 structure types shared by model loading and subject evidence.
+ *
+ * @module
+ */
+/**
+ * STEP source forms accepted by `loadModel`.
+ *
+ * @public
+ */
+type StepSource = string | URL | Uint8Array<ArrayBuffer> | ArrayBuffer | Blob | File | ReadableStream<Uint8Array<ArrayBuffer>> | AsyncIterable<Uint8Array<ArrayBuffer>>;
+/**
+ * STEP reader strategy used by GeoSpec model loading.
+ *
+ * @public
+ */
+type StepStreamingMode = 'auto' | 'native-stream' | 'filesystem';
+/**
+ * One placed occurrence recovered from an AP242 STEP structure read.
+ *
+ * `path` is dot-joined instance-name segments from the root (root omitted) per
+ * the GeoSpec AP242 profile; repeated names under one parent are disambiguated
+ * `name[k]` in the parent's stored component order.
+ *
+ * @public
+ */
+type XdeOccurrence = {
+  path: string;
+  productName: string;
+  instanceName?: string;
+  /** 4x4 row-major placement transform (part-local frame -> subject frame). */
+  transform: number[];
+  /** Index into the native result's retained shape table (proof calls use it). */
+  shapeIndex: number;
+  /** Analytic axis-aligned bounds of the placed occurrence in subject space. */
+  bounds?: {
+    min: [number, number, number];
+    max: [number, number, number];
+  };
+};
+/**
+ * One part-relative authored subshape name, expanded per occurrence of the
+ * owning product (full selector name = `${occurrencePath}.${name}`).
+ *
+ * @public
+ */
+type XdeSubshapeName = {
+  occurrencePath: string;
+  name: string;
+  shapeType: 'face' | 'edge' | 'vertex' | 'solid';
+  /** Index within the owning product shape's deterministic face traversal order. */
+  faceIndex: number;
+};
+/**
+ * One native AP242 datum placement row (a coordinate *frame* from the
+ * supplemental-geometry channel), expanded per occurrence like subshape names
+ * and expressed in subject-frame coordinates.
+ *
+ * Distinct from {@link XdeSemanticDatum}: this is supplemental geometry
+ * (`AXIS2_PLACEMENT_3D` items in a CONSTRUCTIVE_GEOMETRY_REPRESENTATION), not
+ * the GD&T `DATUM` family.
+ *
+ * @public
+ */
+type XdeDatumPlacement = {
+  occurrencePath: string;
+  name: string;
+  origin: [number, number, number];
+  xAxis: [number, number, number];
+  zAxis: [number, number, number];
+};
+/**
+ * One semantic GD&T datum (`DATUM` + `DATUM_FEATURE` family) recovered from an
+ * AP242 file, attached to product faces via GEOMETRIC_ITEM_SPECIFIC_USAGE and
+ * expanded per occurrence of the owning product.
+ *
+ * @public
+ */
+type XdeSemanticDatum = {
+  occurrencePath: string;
+  /** The GD&T datum identification letter(s): 'A', 'B', … */
+  label: string;
+  /** DATUM_FEATURE name when the file authored one. */
+  featureName?: string;
+  /** Attached faces in the owning product's deterministic face traversal order. */
+  faceIndexes: number[];
+};
+/**
+ * One GD&T datum reference frame (`DATUM_SYSTEM`) with its precedence
+ * compartments, expanded per occurrence of the owning product.
+ *
+ * @public
+ */
+type XdeDatumSystem = {
+  occurrencePath: string;
+  name: string;
+  /** Compartments in precedence order; each holds one or more datum labels (common datums). */
+  references: string[][];
+};
+/**
+ * One supplemental-geometry `PLANE` item (e.g. `'Datum Plane 1'`), expanded per
+ * occurrence and expressed in subject-frame millimetres (per-context units
+ * resolved by the reader).
+ *
+ * @public
+ */
+type XdeSupplementalPlane = {
+  occurrencePath: string;
+  name: string;
+  origin: [number, number, number];
+  normal: [number, number, number];
+};
+/**
+ * Structured AP242 read result produced by the GeoSpec verification kernel's
+ * XDE reader (SB1). One STEP-XDE read yields structure and geometry together.
+ *
+ * @public
+ */
+type XdeReadResult = {
+  occurrences: XdeOccurrence[];
+  subshapeNames: XdeSubshapeName[];
+  datumPlacements: XdeDatumPlacement[];
+  /** Semantic GD&T datums (the `DATUM` family) — empty for graphical-only files. */
+  semanticDatums: XdeSemanticDatum[];
+  /** GD&T datum reference frames (`DATUM_SYSTEM`). */
+  datumSystems: XdeDatumSystem[];
+  /** Supplemental-geometry `PLANE` items. */
+  supplementalPlanes: XdeSupplementalPlane[];
+  /** Free (non-assembly) top-level shapes — the flat-export degenerate case. */
+  freeShapeCount: number;
+};
+//#endregion
+export { StepSource, StepStreamingMode, XdeDatumPlacement, XdeDatumSystem, XdeOccurrence, XdeReadResult, XdeSemanticDatum, XdeSubshapeName, XdeSupplementalPlane };

package/dist/vitest/adapter.d.mts

@@ -0,0 +1,56 @@
+import { GeoSpecSubject } from "../model/subject.mjs";
+import { GeoSpecCanonicalClaimReport, GeoSpecNativeSubject } from "../engine/client.mjs";
+import { GeoSpecAssertionClient, GeoSpecAssertionClientOptions, GeoSpecMatcherMethods } from "../assertion-client/client.mjs";
+import "../assertion-client/index.mjs";
+import { MatcherState } from "vitest";
+//#region src/vitest/adapter.d.ts
+type GeoSpecVitestMatcherMethods = GeoSpecMatcherMethods<Promise<void>>;
+type GeoSpecVitestResult = {
+  readonly actual: GeoSpecCanonicalClaimReport;
+  readonly expected: Readonly<{
+    claimId: string;
+    polarity: string;
+    status: string;
+  }>;
+  readonly message: () => string;
+  readonly meta: Readonly<{
+    geoSpec: GeoSpecCanonicalClaimReport;
+  }>;
+  readonly pass: boolean;
+};
+type GeoSpecVitestMatcher = (this: MatcherState, received: GeoSpecNativeSubject | GeoSpecSubject | PromiseLike<GeoSpecNativeSubject | GeoSpecSubject>, ...arguments_: readonly unknown[]) => Promise<GeoSpecVitestResult>;
+type GeoSpecVitestMatcherMap = Record<string, GeoSpecVitestMatcher>;
+declare module 'vitest' {
+  interface Matchers<T = any> extends GeoSpecVitestMatcherMethods {}
+}
+/** Installed Vitest matcher map and lifecycle settlement hook. @public */
+type GeoSpecVitestAdapter = {
+  readonly matchers: GeoSpecVitestMatcherMap;
+  flush(): Promise<void>;
+};
+/**
+ * Create Vitest matchers over an existing runner-independent client.
+ *
+ * @param client - Native GeoSpec assertion client shared with standalone use.
+ * @returns Matchers and a hook that settles every operation started by a test.
+ * @public
+ */
+declare const createGeoSpecVitestAdapter: (client: GeoSpecAssertionClient) => GeoSpecVitestAdapter;
+/**
+ * Register GeoSpec matchers and their settlement hook in the active Vitest file.
+ *
+ * @param client - Native client shared with standalone assertion calls.
+ * @returns The installed adapter for reporters or explicit flushing.
+ * @public
+ */
+declare const installGeoSpecVitest: (client: GeoSpecAssertionClient) => GeoSpecVitestAdapter;
+/**
+ * Create a native client and register it with the active Vitest file.
+ *
+ * @param options - Flat native assertion-client options.
+ * @returns The installed adapter for reporters or explicit flushing.
+ * @public
+ */
+declare const setupGeoSpecVitest: (options: GeoSpecAssertionClientOptions) => GeoSpecVitestAdapter;
+//#endregion
+export { GeoSpecVitestAdapter, createGeoSpecVitestAdapter, installGeoSpecVitest, setupGeoSpecVitest };

package/dist/vitest/adapter.mjs

@@ -0,0 +1,3 @@
+import{geoSpecMatcherDescriptors as e}from"../engine/matchers.mjs";import{GeoSpecAssertionError as t,createGeoSpecAssertionClient as n}from"../assertion-client/client.mjs";import{afterEach as r,expect as i}from"vitest";const a=e=>e.evidence!==null&&typeof e.evidence==`object`&&!Array.isArray(e.evidence)?e.evidence:void 0,o=(e,t)=>{let n=a(t)?.positiveSatisfied;return{pass:(t.status===`passed`||t.status===`failed`)&&typeof n==`boolean`&&t.status===`passed`==(n===(t.polarity===`positive`))?n:e.isNot,actual:t,expected:{claimId:t.claimId,polarity:t.polarity,status:t.status},meta:{geoSpec:t},message:()=>JSON.stringify(t.result)}};var s=class{task;tracked=[];constructor(e){this.task=e,e.onFinished??=[],e.onFinished.push(()=>{for(;this.tracked.length>0;){let[e]=this.tracked;if(e===void 0)break;this.remove(e)}})}replace(e,t){return this.remove(e),this.track(t)}track(e){let t=new c(e,this);return this.task.promises??=[],this.task.promises.push(t),this.tracked.push(t),t}remove(e){let t=this.task.promises?.indexOf(e)??-1;t!==-1&&this.task.promises?.splice(t,1);let n=this.tracked.indexOf(e);n!==-1&&this.tracked.splice(n,1)}},c=class{promise;tracker;constructor(e,t){this.promise=e,this.tracker=t,e.catch(()=>void 0)}get[Symbol.toStringTag](){return`Promise`}then(e,t){return this.tracker.replace(this,this.promise.then(e,t))}catch(e){return this.tracker.replace(this,this.promise.catch(e))}finally(e){return this.tracker.replace(this,this.promise.finally(e))}},l=class{invocationStack;promise;task;constructor(e,t,n){this.promise=e,this.task=t,this.invocationStack=n}get[Symbol.toStringTag](){return`Promise`}then(e,t){let n=this.promise.then(e,t).catch(e=>{if(e instanceof Error&&this.invocationStack!==void 0){let t=this.invocationStack.split(`
+`).slice(1).join(`
+`);e.stack=`${e.stack??e.message}\nGeoSpec assertion invoked at:\n${t}`}throw e});return this.task===void 0?n:new s(this.task).track(n)}catch(e){return this.promise.catch(e)}finally(e){return this.promise.finally(e)}};const u=n=>{let r=new Set,i={};for(let a of Object.keys(e))i[a]=function(e,...i){if(!Reflect.has(this,`assertion`))throw TypeError(`GeoSpec Vitest matchers do not support asymmetric use.`);let s=Reflect.get(this,`task`),c=(async()=>{let r=await e,o=n.expectGeo(r),s=this.isNot?o.not:o;try{return Reflect.apply(s[a],s,i)}catch(e){if(e instanceof t)return e.report;throw e}})();return s===void 0&&r.add(c),new l((async()=>o(this,await c))(),s,Error(`Track GeoSpec assertion origin.`).stack)};let a=async()=>{let e=[...r];r.clear();let n=(await Promise.all(e)).find(e=>e.status!==`passed`);if(n!==void 0)throw new t(n);r.size>0&&await a()};return{matchers:i,flush:a}},d=e=>{let t=u(e);return i.extend(t.matchers),r(async()=>t.flush()),t},f=e=>d(n(e));export{u as createGeoSpecVitestAdapter,d as installGeoSpecVitest,f as setupGeoSpecVitest};

package/dist/vitest/index.d.mts

@@ -0,0 +1,4 @@
+import { GeoSpecAssertionClient, GeoSpecAssertionClientOptions } from "../assertion-client/client.mjs";
+import "../assertion-client/index.mjs";
+import { GeoSpecVitestAdapter, createGeoSpecVitestAdapter, installGeoSpecVitest, setupGeoSpecVitest } from "./adapter.mjs";
+export { type GeoSpecAssertionClient, type GeoSpecAssertionClientOptions, type GeoSpecVitestAdapter, createGeoSpecVitestAdapter, installGeoSpecVitest, setupGeoSpecVitest };

package/dist/vitest/index.mjs

@@ -0,0 +1 @@
+import{createGeoSpecVitestAdapter as e,installGeoSpecVitest as t,setupGeoSpecVitest as n}from"./adapter.mjs";export{e as createGeoSpecVitestAdapter,t as installGeoSpecVitest,n as setupGeoSpecVitest};