geospec 0.0.0 → 0.1.0-beta.2

package/dist/model/load-model.mjs

@@ -0,0 +1 @@
+import{bindGeoSpecSubject as e,rawSubjectResidency as t}from"./subject.mjs";import{createGeoSpecAssertionClient as n}from"../assertion-client/client.mjs";import{GeoSpecModelLoadError as r}from"./errors.mjs";import{createGeoSpecNativeModelLoader as i}from"./native-model-loader.mjs";async function a(e){throw new r([{code:`GEOSPEC_MODEL_LOADER_UNAVAILABLE`,severity:`error`,message:`No GeoSpec model loader is active outside a GeoSpec runner.`,suggestion:`Run this test through the GeoSpec CLI or Tau test runner, or call createModelLoader({ engine }).`}])}const o=r=>{let{engine:a,readSource:o,format:s,...c}=r,l={...c,...s===void 0?{}:{format:s}},u=i({...c,engine:a,...o===void 0?{}:{readSource:o}}),d=n({engine:a}),f=0;return Object.assign(async n=>{let r=f,i=await u({...l,...n}),o=t(i);return e({client:d,engine:a,identity:{subjectHash:i.subjectHash},...i.load===void 0?{}:{load:i.load},isLive:()=>f===r,...o===void 0?{}:{ensureResident:o}})},{async dispose(){try{await u.releaseAll()}finally{f+=1}}})};export{o as createModelLoader,a as loadModel};

package/dist/model/native-model-loader.d.mts

@@ -0,0 +1,119 @@
+import { GeoSpecModelFormat, GeoSpecRuntimeClient, GeoSpecRuntimeClientFactory, GeoSpecRuntimeSourceAdapter, LoadModelOptions, LoadModelSourceOptions } from "./types.mjs";
+import { GeoSpecNativeEngine, GeoSpecNativeSubject } from "../engine/client.mjs";
+import "../assertion-client/index.mjs";
+import { SourceRevision } from "@taucad/runtime/types";
+//#region src/model/native-model-loader.d.ts
+/** Native engine operations required for model admission and run-level cleanup. @public */
+type GeoSpecNativeModelEngine = GeoSpecNativeEngine & {
+  ingestSubject(request: Uint8Array<ArrayBuffer>, primary: Uint8Array<ArrayBuffer>, resources: ReadonlyArray<Uint8Array<ArrayBuffer>>): Uint8Array<ArrayBuffer>;
+  subjectHandle(request: Uint8Array<ArrayBuffer>): Uint8Array<ArrayBuffer>;
+  releaseSubject(request: Uint8Array<ArrayBuffer>): Uint8Array<ArrayBuffer>;
+};
+/** One named external resource referenced by a direct glTF-family source. @public */
+type GeoSpecNativeModelResource = {
+  readonly name: string;
+  readonly source: LoadModelSourceOptions['source'];
+};
+/** Native additions accepted by the injected `geospec/runner/native` loader. @public */
+type GeoSpecNativeLoadModelOptions<Code extends Record<string, string> = Record<string, string>> = LoadModelOptions<Code> & {
+  /** Ordered external resource payloads declared to the native admission request. */
+  readonly resources?: readonly GeoSpecNativeModelResource[];
+  /** Format-specific native ingest options. */
+  readonly ingestOptions?: Readonly<Record<string, unknown>>;
+};
+/** Subject identity returned by native STEP/GLB admission. @public */
+type GeoSpecNativeModelSubject = GeoSpecNativeSubject & {
+  readonly subjectHash: string;
+  /** Exact successful-load evidence retained by the admitting host, when available. */
+  readonly load?: GeoSpecModelLoadEvidence;
+};
+/** Immutable identity of the inputs and artifacts consumed by one model load. @public */
+type GeoSpecModelLoadEvidence = {
+  readonly loadId: string;
+  readonly status: 'complete' | 'unavailable';
+  readonly format: string;
+  readonly parameters: Readonly<Record<string, unknown>>;
+  readonly exportOptions?: Readonly<Record<string, unknown>>;
+  readonly ingestOptions: Readonly<Record<string, unknown>>;
+  readonly sourceRevision?: SourceRevision;
+  /** Actual direct-source locator, when the load read one; absent for anonymous in-memory bytes. */
+  readonly sourcePath?: string;
+  readonly artifacts: ReadonlyArray<{
+    readonly name: string;
+    readonly sha256: string;
+    readonly byteLength: number;
+    /** Actual source locator consumed by a direct load; absent for bytes and Runtime exports. */
+    readonly sourcePath?: string;
+  }>;
+};
+/**
+ * Resolve a non-memory source into ordinary ArrayBuffer-backed bytes.
+ *
+ * The loader takes ownership of the returned bytes and admits them without a
+ * copy, so a reader must return bytes that nothing mutates afterwards (a fresh
+ * read, not a view of a shared or reused buffer).
+ *
+ * @public
+ */
+type GeoSpecNativeSourceReader = (source: LoadModelSourceOptions['source']) => Promise<Uint8Array<ArrayBuffer>>;
+/** Defaults and host dependencies for a managed native model loader. @public */
+type CreateGeoSpecNativeModelLoaderOptions = {
+  readonly engine: GeoSpecNativeModelEngine;
+  readonly format?: Extract<GeoSpecModelFormat, 'glb' | 'step' | 'stp'>;
+  readonly projectPath?: string;
+  readonly readSource?: GeoSpecNativeSourceReader;
+  readonly runtime?: GeoSpecRuntimeClient | GeoSpecRuntimeClientFactory;
+  readonly sourceAdapters?: readonly GeoSpecRuntimeSourceAdapter[];
+  /**
+   * Subject handles carried between the release scopes of loaders that share one engine, keyed by
+   * subjectHash. With a carrier, `releaseAll` keeps this scope's subjects for the next scope and
+   * releases only the previous scope's subjects this scope did not load again, so reloading
+   * unchanged bytes in the next scope is digest-only. Share one carrier per engine and run its
+   * scopes one at a time: a scope's release touches only subjects whose scope has settled.
+   */
+  readonly carried?: Map<string, unknown>;
+};
+/**
+ * Model loader injected into native VM runs.
+ *
+ * The freshness unit is one load: every call reads its source again (the
+ * source reader or a Runtime export) and the engine digests those exact bytes.
+ * Nothing is deduplicated per run or per scope; bytes equal to an admitted
+ * subject's reuse that subject by digest, length and descriptor, and edited
+ * bytes admit a new subject. Only concurrent identical inline-code Runtime
+ * loads share one in-flight export.
+ *
+ * @public
+ */
+type GeoSpecNativeModelLoader = <Code extends Record<string, string> = Record<string, string>>(options: GeoSpecNativeLoadModelOptions<Code>) => Promise<GeoSpecNativeModelSubject>;
+/**
+ * Reusable native model loader whose admitted subjects can be released as one run.
+ * The caller owns the engine and the boundaries between load scopes.
+ * @public
+ */
+type ManagedGeoSpecNativeModelLoader = GeoSpecNativeModelLoader & {
+  /**
+   * Drain registered admissions, including additions while drainage awaits,
+   * then release this scope's subjects (with a carrier: the previous scope's
+   * subjects this scope did not load again) and owned Runtime clients.
+   *
+   * Await the intended complete load chain before final release, and await
+   * this method before closing the caller-owned engine. Calls after it returns
+   * start a new scope requiring another release; future detached loads are not
+   * part of the completed scope.
+   *
+   * @returns Completion of the current scope's admission drain and release.
+   */
+  releaseAll(): Promise<void>;
+};
+/**
+ * Create a native model loader that admits actual STEP/GLB bytes and retains
+ * generation-checked handles until the owning runner finishes.
+ *
+ * @param defaults - Native engine, Runtime defaults, and optional source reader.
+ * @returns A loader plus run-level cleanup operation.
+ * @public
+ */
+declare const createGeoSpecNativeModelLoader: (defaults: CreateGeoSpecNativeModelLoaderOptions) => ManagedGeoSpecNativeModelLoader;
+//#endregion
+export { CreateGeoSpecNativeModelLoaderOptions, GeoSpecModelLoadEvidence, GeoSpecNativeLoadModelOptions, GeoSpecNativeModelEngine, GeoSpecNativeModelLoader, GeoSpecNativeModelResource, GeoSpecNativeModelSubject, GeoSpecNativeSourceReader, ManagedGeoSpecNativeModelLoader, createGeoSpecNativeModelLoader };

package/dist/model/native-model-loader.mjs

@@ -0,0 +1 @@
+import{bindRawSubjectResidency as e}from"./subject.mjs";import{GeoSpecModelLoadError as t}from"./errors.mjs";import{resolveRuntimeExportIntent as n}from"./export-intent.mjs";import{sha256Bytes as r}from"@taucad/runtime/kernel";const i={canonicalProfile:`geospec-jcs-v1`,protocolVersion:3,registryVersion:5},a=new TextEncoder,o=new TextDecoder(`utf-8`,{fatal:!0}),s=new Set([`glb`,`step`,`stp`]),c=new WeakMap,l=16777216,u=e=>e instanceof Error&&`code`in e&&e.code===`limit-exceeded`&&e.message===`Engine exceeds the configured retained subject count.`,d=e=>{let t=c.get(e);if(t!==void 0)return t;let n=_(e.processRequest(h({...i,method:`initialize`,requestId:`configuration`})),`initialize response`),r=g(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 a=g(r.configuration,`initialize configuration`),o=g(a.binaryAdmissionLimits,`binary admission limits`),s=[o.maxSubjectBytes,o.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}),l={inputs:new Map,resident:new Map,binaryLimit:Math.max(...s),binaryBytes:0,descriptorBytes:0};return c.set(e,l),l},f=e=>new t(e),p=e=>({code:e.code,severity:`error`,message:e.message,suggestion:e.suggestion,...e.details===void 0?{}:{details:e.details}}),m=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.`}),h=e=>a.encode(JSON.stringify(e)),g=(e,t)=>{if(typeof e!=`object`||!e||Array.isArray(e))throw TypeError(`Native GeoSpec returned a non-object ${t}.`);return e},_=(e,t)=>g(JSON.parse(o.decode(e)),t),v=async(e,t)=>{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){throw f([p({code:`GEOSPEC_NATIVE_SOURCE_READ_FAILED`,message:`The host source reader could not read ${typeof e==`string`?e:`this source`}: ${t instanceof Error?t.message:String(t)}`,suggestion:`Check that the source exists at a project-rooted path and is readable, then retry the load.`,...typeof e==`string`?{details:{source:e}}:{}})])}throw f([p({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().`})])},y=e=>`code`in e?{files:e.code,entry:e.file}:{path:e.file},b=(e,t)=>{let n=e.format??t??`glb`;if(!s.has(n))throw f([p({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},x=t=>{let a=0,o=new Map,s=new Map,x=0,S=new Set,C=new Map,w=new Set,T=new Map,E=e=>(a+=1,`geospec-native-model:${e}:${a}`),D=e=>(e.sourceAdapters??t.sourceAdapters)?.find(t=>t.extensions.some(t=>e.file.endsWith(t))),O=async e=>{let n=e.runtime??t.runtime;if(typeof n==`function`){let e=T.get(n);e===void 0&&(e=n(),T.set(n,e));let t=await e;return w.add(t),t}if(n!==void 0)return n;let r=D(e);if(r!==void 0){let n=await r.createRuntime({file:e.file,...(e.projectPath??t.projectPath)===void 0?{}:{projectPath:e.projectPath??t.projectPath}});return w.add(n),n}throw f([p({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}})])},k=e=>{t.engine.releaseSubject(h({...i,method:`releaseSubject`,requestId:E(`release`),subjectHandle:e}))},A=(e,n)=>{let r=c.get(t.engine),i=r?.inputs.get(e);if(r!==void 0&&i!==void 0&&(i.cleanupPending?.(),delete i.cleanupPending,i.owners.has(n))){if(i.owners.size>1){i.owners.delete(n);return}i.handle!==void 0&&(k(i.handle),delete i.handle),i.owners.delete(n),r.resident.delete(e),r.inputs.delete(e),r.binaryBytes-=i.resources.reduce((e,t)=>e+t.byteLength,i.primary.byteLength),r.descriptorBytes-=i.request.byteLength}},j=e=>{for(let[t,n]of e.inputs)n.cleanupPending!==void 0&&(n.cleanupPending(),delete n.cleanupPending,delete n.handle,e.resident.delete(t))},M=()=>[...t.carried??[]].filter(([e])=>!o.has(e)),N=(e,n)=>{let r=e.format===`stp`?`step`:e.format,a=d(t.engine);j(a);let c=h({...i,method:`ingestSubject`,requestId:E(`ingest`),format:r,frame:{coordinateSystem:`z-up`,sourceUnit:r===`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}))}),f=e.resources.reduce((e,{bytes:t})=>e+t.byteLength,e.primary.byteLength);if(!Number.isSafeInteger(f)||f>a.binaryLimit||c.byteLength>l)throw Object.assign(RangeError(`GeoSpec retained admission input exceeds its byte limit.`),{code:`limit-exceeded`});let p=(e,t)=>e.length===t.length&&e.every((e,n)=>e===t[n]),m={..._(c,`admission request`),requestId:``},v=[...a.inputs.values()].find(t=>{let n={..._(t.request,`retained request`),requestId:``};return JSON.stringify(n)===JSON.stringify(m)&&p(t.primary,e.primary)&&t.resources.length===e.resources.length&&t.resources.every((t,n)=>p(t,e.resources[n].bytes))});if(v===void 0&&(f>a.binaryLimit-a.binaryBytes||c.byteLength>l-a.descriptorBytes))throw Object.assign(RangeError(`GeoSpec live admission snapshots exceed their retained input byte limit.`),{code:`limit-exceeded`});let y=v??{request:Uint8Array.from(c),primary:Uint8Array.from(e.primary),resources:e.resources.map(({bytes:e})=>Uint8Array.from(e)),owners:new Set},b=()=>t.engine.ingestSubject(c,e.primary,e.resources.map(({bytes:e})=>e)),x;try{x=b()}catch(e){let n=M();if(!u(e))throw e;let r=!1;for(let[e,i]of n){let n=a.inputs.get(e);if(n===void 0)k(i),r=!0;else{let i=n.owners.size===1&&n.handle!==void 0;A(e,t.carried),r||=i}t.carried?.delete(e)}if(!r){let t=a.resident.entries().next().value;if(t===void 0)throw e;k(t[1].handle),delete t[1].handle,a.resident.delete(t[0])}x=b()}let S=_(x,`admission response`),C=g(S.result,`admission result`),{subjectHash:w}=g(C.subject,`admitted subject`);if(typeof w!=`string`||!/^[0-9a-f]{64}$/u.test(w))throw TypeError(`Native GeoSpec admission did not return a valid subjectHash.`);let T=_(t.engine.subjectHandle(h({...i,method:`subjectHandle`,requestId:E(`handle`),subjectHash:w})),`subject-handle response`),D=g(T.result,`subject-handle result`).subjectHandle;if(D===void 0)throw TypeError(`Native GeoSpec did not return a subject handle.`);let O=a.inputs.get(w),N=O??y;O===void 0&&(a.inputs.set(w,N),a.binaryBytes+=f,a.descriptorBytes+=N.request.byteLength);for(let e of n)N.owners.add(e),s.set(e,w);return N.handle=D,a.resident.delete(w),a.resident.set(w,N),o.set(w,N),{subjectHash:w}},P=e=>{let n=o.get(e);if(n===void 0)throw TypeError(`This subject is not admitted by the active GeoSpec host.`);let r=d(t.engine);if(j(r),n.handle===void 0){let a=()=>t.engine.ingestSubject(n.request,n.primary,n.resources),o;try{o=a()}catch(e){let t=r.resident.entries().next().value;if(!u(e)||t===void 0)throw e;k(t[1].handle),delete t[1].handle,r.resident.delete(t[0]),o=a()}let s=()=>{let n=g(_(t.engine.subjectHandle(h({...i,method:`subjectHandle`,requestId:E(`restore-handle`),subjectHash:e})),`restored handle`).result,`restored handle result`),r=g(n.subjectHandle,`restored subject handle`);if(r.subjectHash!==e)throw TypeError(`Native GeoSpec restored handle changed its subject identity.`);return r};try{if(g(g(_(o,`restored admission`).result,`restored result`).subject,`restored subject`).subjectHash!==e)throw TypeError(`Native GeoSpec restored admission changed its subject identity.`);n.handle=s()}catch(e){throw n.cleanupPending=()=>{try{k(s())}catch(t){throw AggregateError([e,t],`Native GeoSpec restored admission failed and cleanup remains pending.`,{cause:e})}},n.cleanupPending(),delete n.cleanupPending,e}}r.resident.delete(e),r.resident.set(e,n)},F=async(e,n)=>{let i=b(e,t.format),a=await v(e.source,t.readSource),o=await Promise.all((e.resources??[]).map(async({name:e,source:n})=>({name:e,bytes:await v(n,t.readSource),...typeof n==`string`?{sourcePath:n}:{}}))),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 r(t),byteLength:t.byteLength,...n===void 0?{}:{sourcePath:n}})));return{...N({format:i,primary:a,resources:o,...e.ingestOptions===void 0?{}:{ingestOptions:e.ingestOptions},...e.sourceUnit===void 0?{}:{sourceUnit:e.sourceUnit}},n),load:{loadId:``,status:`complete`,format:i,parameters:e.parameters??{},ingestOptions:e.ingestOptions??{},...typeof e.source==`string`?{sourcePath:e.source}:{},artifacts:s}}},I=async(e,i)=>{for(let t of[`sourceUnit`,`unit`,`scale`,`coordinateSystem`])if(t in e)throw f([p({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 a=b(e,t.format),o=a===`stp`?`step`:a,s=await O(e);await s.connect();let c={runtime:s,format:o,...e.meshLinearTolerance===void 0?{}:{meshLinearTolerance:e.meshLinearTolerance},...e.meshAngularToleranceDegrees===void 0?{}:{meshAngularToleranceDegrees:e.meshAngularToleranceDegrees}},l=n(c);if(`success`in l)throw f(l.diagnostics);let u=structuredClone(l.options),d=s.open({source:y(e),...e.parameters===void 0?{}:{parameters:e.parameters},watch:!1}),h=await(async()=>{try{return await d.export(o,{options:structuredClone(u)})}finally{d.close()}})();if(!h.success)throw f(h.issues.map(m));let g=[...h.files],[_,...v]=g;if(_===void 0)throw f([p({code:`GEOSPEC_NATIVE_MODEL_EXPORT_EMPTY`,message:`The Tau Runtime exported no ${o.toUpperCase()} artifact for '${e.file}'.`,suggestion:`Check that the selected source exports geometry in the requested format.`,details:{file:e.file,format:o}})]);let x=n(c);if(`success`in x)throw f(x.diagnostics);let S=await Promise.all(g.map(async({name:e,bytes:t})=>({name:e,sha256:await r(t),byteLength:t.byteLength}))),C=h.sourceRevision===void 0?void 0:structuredClone(h.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{...N({format:o,primary:_.bytes,resources:v,sourceUnit:x.sourceUnit,diagnostics:h.issues.map(m),...e.ingestOptions===void 0?{}:{ingestOptions:e.ingestOptions}},i),load:{loadId:``,status:w?`complete`:`unavailable`,format:o,parameters:e.parameters??{},exportOptions:u,ingestOptions:e.ingestOptions??{},...C===void 0?{}:{sourceRevision:C},artifacts:S}}},L=async(e,n)=>{let r=e.runtime??t.runtime;if(!(`code`in e)||r===void 0||e.parameters!==void 0||e.ingestOptions!==void 0||[`sourceUnit`,`unit`,`scale`,`coordinateSystem`].some(t=>t in e))return I(e,new Set([n]));let i=Object.getPrototypeOf(e.code);if(i!==Object.prototype&&i!==null||Object.values(Object.getOwnPropertyDescriptors(e.code)).some(e=>!(`value`in e)||typeof e.value!=`string`))return I(e,new Set([n]));let a=Object.entries(e.code),o=Object.fromEntries(a),s=JSON.stringify({file:e.file,files:a,format:e.format??t.format??`glb`,meshLinearTolerance:e.meshLinearTolerance,meshAngularToleranceDegrees:e.meshAngularToleranceDegrees}),c=C.get(r);c===void 0&&(c=new Map,C.set(r,c));let l=c.get(s);if(l!==void 0)return l.owners.add(n),l.pending;let u=new Set([n]),d=I({...e,code:o},u);c.set(s,{pending:d,owners:u});let f=()=>{c.delete(s),c.size===0&&C.delete(r)};return d.then(f,f),d};return Object.assign(n=>{let r={},i=E(`load`),a={...n,...`code`in n?{code:Object.fromEntries(Object.entries(n.code))}:{},...n.parameters===void 0?{}:{parameters:structuredClone(n.parameters)},...n.ingestOptions===void 0?{}:{ingestOptions:structuredClone(n.ingestOptions)}},c=n.format??t.format??`glb`,l=[`stepStreaming`,...n.mesh===!1&&(c===`step`||c===`stp`)?[]:[`mesh`],...`source`in n?[`meshLinearTolerance`,`meshAngularToleranceDegrees`,...c===`step`||c===`stp`?[`sourceUnit`]:[]]:[]].find(e=>e in n);if(l!==void 0)return Promise.reject(f([p({code:`GEOSPEC_MODEL_OPTION_UNSUPPORTED`,message:`This GeoSpec host cannot honor model option '${l}'.`,suggestion:`Remove this option or configure a host that supports its declared behavior.`,details:{option:l}})]));let u=`source`in n?F(a,new Set([r])):L(a,r),d=(async()=>{let t=await u,n={...t,...t.load===void 0?{}:{load:{...t.load,loadId:i}}},a=x,c=!1;return e(n,{ensureResident(){if(a!==x||!s.has(r))throw TypeError(`This subject is not admitted by the active GeoSpec host.`);P(t.subjectHash)},dispose(){if(!(c||!s.has(r))){c=!0;try{A(t.subjectHash,r),s.delete(r),[...s.values()].includes(t.subjectHash)||o.delete(t.subjectHash)}finally{c=!1}}}}),n})();return S.add(d),d},{async releaseAll(){do{let e=[...S];await Promise.allSettled(e);for(let t of e)S.delete(t)}while(S.size>0);let e=[],{carried:n}=t;if(x+=1,n!==void 0){for(let[r,i]of M())try{c.get(t.engine)?.inputs.has(r)?A(r,n):k(i),n.delete(r)}catch(t){e.push(t)}for(let[e,t]of o)t.handle===void 0?(t.owners.delete(n),n.delete(e)):(t.owners.add(n),n.set(e,t.handle))}for(let[t,n]of[...s].reverse())try{A(n,t),s.delete(t),[...s.values()].includes(n)||o.delete(n)}catch(t){e.push(t)}for(let t of w)try{t.shutdown?await t.shutdown():t.terminate()}catch(t){e.push(t)}if(w.clear(),T.clear(),e.length>0)throw AggregateError(e,`Native GeoSpec model cleanup failed.`)}})};export{x as createGeoSpecNativeModelLoader};

package/dist/model/subject-assertions.mjs

@@ -0,0 +1 @@
+import{resolveGeoSpecSubject as e}from"./subject.mjs";import{createGeoSpecMatcherMethods as t}from"../assertion-client/client.mjs";import{diagnosticForTransport as n,geometryDiagnosticSchema as r}from"./errors.mjs";const i=i=>{let a=e(i),o=a.client.expectGeo(a.identity),s=s=>t({subject:i,polarity:s?`negative`:`positive`,invoke:t=>{e(i);let c=s?o.not:o,l=Reflect.apply(c[t.matcher],c,t.arguments),u=l.diagnostics.map(e=>n(r.parse(e)));return{kind:t.kind,subject:a.identity,...a.load===void 0?{}:{loadId:a.load.loadId},expected:t.expected,passed:l.status===`passed`,diagnostics:u,report:l}}});return Object.assign(s(!1),{not:s(!0)})};export{i as expectGeoSubject};

package/dist/model/subject.d.mts

@@ -0,0 +1,11 @@
+import "./native-model-loader.mjs";
+import "../engine/client.mjs";
+import "../assertion-client/client.mjs";
+//#region src/model/subject.d.ts
+declare const subjectBrand: unique symbol;
+/** A model admitted by one live GeoSpec host scope. Load it through `geospec/model`. @public */
+type GeoSpecSubject = {
+  readonly [subjectBrand]: true;
+};
+//#endregion
+export { GeoSpecSubject };

package/dist/model/subject.mjs

@@ -0,0 +1 @@
+const e=new WeakMap,t=new WeakMap,n=(n,r)=>{e.set(n,r),t.set(r.ensureResident,r)},r=t=>e.get(t)?.ensureResident,i=new WeakMap,a=e=>{let n=Object.freeze({});return i.set(n,{client:e.client,engine:e.engine,identity:e.identity,isLive:e.isLive,...e.load===void 0?{}:{load:e.load},...e.ensureResident===void 0?{}:{ensureResident:e.ensureResident},...e.ensureResident===void 0||!t.has(e.ensureResident)?{}:{lease:t.get(e.ensureResident)}}),n},o=(e,t)=>{let n=typeof e==`object`&&e?i.get(e):void 0;if(n===void 0||!n.isLive()||t!==void 0&&n.engine!==t)throw Object.assign(TypeError(`This subject is not admitted by the active GeoSpec host. Reload it within its live scope.`),{code:`GEOSPEC_SUBJECT_INVALID`});return n.ensureResident?.(),n};export{a as bindGeoSpecSubject,n as bindRawSubjectResidency,r as rawSubjectResidency,o as resolveGeoSpecSubject};

package/dist/model/types.d.mts

@@ -0,0 +1,207 @@
+import { GeoSpecUnit } from "../geometry-unit.mjs";
+import { StepSource, StepStreamingMode } from "../step/types.mjs";
+import { MeshFileFormat } from "../mesh/types.mjs";
+import { GeoSpecSubject } from "./subject.mjs";
+import { GeoSpecNativeModelEngine, GeoSpecNativeSourceReader } from "./native-model-loader.mjs";
+import { RuntimeClient } from "@taucad/runtime";
+//#region src/model/types.d.ts
+/**
+ * In-memory triangle mesh source.
+ *
+ * @public
+ */
+type MeshBufferSource = {
+  format: 'mesh-buffer';
+  positions: Float32Array<ArrayBuffer> | number[];
+  indices?: Uint32Array<ArrayBuffer> | Uint16Array<ArrayBuffer> | number[];
+  name?: string;
+};
+/**
+ * Mesh source forms accepted by {@link import('./load-model.js').loadModel}.
+ *
+ * @public
+ */
+type MeshSource = Uint8Array<ArrayBuffer> | ArrayBuffer | Blob | File | URL | string | MeshBufferSource;
+/**
+ * Geometry formats accepted by {@link import('./load-model.js').loadModel}.
+ *
+ * @public
+ */
+type GeoSpecModelFormat = MeshFileFormat | 'step' | 'stp';
+/**
+ * Runtime client surface consumed by `geospec/model`.
+ *
+ * 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.
+ *
+ * @public
+ */
+type GeoSpecRuntimeClient = Pick<RuntimeClient, 'connect' | 'terminate'> & Partial<Pick<RuntimeClient, 'shutdown'>> & {
+  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<{
+      name: string;
+      duration: number;
+      startTime: number;
+      workerTimeOrigin: number;
+    }>;
+  }) => void): () => void;
+};
+/**
+ * Lazy runtime factory consumed by `geospec/model`.
+ *
+ * @public
+ */
+type GeoSpecRuntimeClientFactory = () => Promise<GeoSpecRuntimeClient>;
+/**
+ * Explicit source adapter for formats whose runtime setup is not part of the
+ * generic Tau runtime preset.
+ *
+ * @public
+ */
+type GeoSpecRuntimeSourceAdapter = {
+  id: string;
+  extensions: readonly string[];
+  createRuntime(options: {
+    projectPath?: string;
+    file?: string;
+  }): Promise<GeoSpecRuntimeClient>;
+};
+/**
+ * Direct geometry-source model load options.
+ *
+ * @public
+ */
+type LoadModelSourceOptions = {
+  /** Geometry bytes, path, browser file/blob, or in-memory mesh buffer. */
+  source: MeshSource | StepSource;
+  /** Named external resources consumed alongside the direct geometry bytes. */
+  resources?: ReadonlyArray<{
+    readonly name: string;
+    readonly source: MeshSource | StepSource;
+  }>;
+  /** Source geometry format. Defaults to `glb`. */
+  format?: GeoSpecModelFormat;
+  /** Source path recorded in provenance. */
+  path?: string;
+  /** Human-readable source name recorded in provenance. */
+  name?: string;
+  /** Coordinate unit of raw GLB/glTF or mesh-buffer data before canonical millimetre normalization. */
+  sourceUnit?: GeoSpecUnit;
+  /** Explicit parameters recorded in provenance. */
+  parameters?: Record<string, unknown>;
+  /** STEP reader strategy used for STEP sources. */
+  stepStreaming?: StepStreamingMode;
+  /** Whether STEP loading should also produce mesh evidence. Defaults to true. */
+  mesh?: boolean;
+  /** Linear tolerance used while meshing exact BRep evidence. */
+  meshLinearTolerance?: number;
+  /** Angular tolerance in degrees used while meshing exact BRep evidence. */
+  meshAngularToleranceDegrees?: number;
+};
+/**
+ * Inline code-CAD model load options.
+ *
+ * @public
+ */
+type LoadModelCodeOptions<Code extends Record<string, string> = Record<string, string>> = {
+  /** Source files keyed by project-relative path. */
+  code: Code;
+  /** Entry path to render from {@link code}. */
+  file: keyof Code & string;
+  /** Geometry format to export. Defaults to `glb`. */
+  format?: GeoSpecModelFormat;
+  /** Explicit parameters passed to the runtime. */
+  parameters?: Record<string, unknown>;
+  /** Runtime client or lazy runtime factory. */
+  runtime?: GeoSpecRuntimeClient | GeoSpecRuntimeClientFactory;
+  /** Source-specific runtime adapters, e.g. host-provided GPL-isolated kernels. */
+  sourceAdapters?: readonly GeoSpecRuntimeSourceAdapter[];
+  /** Project root used by runtime integrations. */
+  projectPath?: string;
+  /** STEP reader strategy used for STEP exports. */
+  stepStreaming?: StepStreamingMode;
+  /** Whether STEP loading should also produce mesh evidence. Defaults to true. */
+  mesh?: boolean;
+  /** Linear tolerance used while meshing exact BRep evidence. */
+  meshLinearTolerance?: number;
+  /** Angular tolerance in degrees used while meshing exact BRep evidence. */
+  meshAngularToleranceDegrees?: number;
+};
+/**
+ * Filesystem-backed model load options.
+ *
+ * @public
+ */
+type LoadModelFileOptions = {
+  /** Project-relative model file to render. */
+  file: string;
+  /** Project root used by runtime integrations. */
+  projectPath?: string;
+  /** Geometry format to export. Defaults to `glb`. */
+  format?: GeoSpecModelFormat;
+  /** Explicit parameters passed to the runtime. */
+  parameters?: Record<string, unknown>;
+  /** Runtime client or lazy runtime factory. */
+  runtime?: GeoSpecRuntimeClient | GeoSpecRuntimeClientFactory;
+  /** Source-specific runtime adapters, e.g. host-provided GPL-isolated kernels. */
+  sourceAdapters?: readonly GeoSpecRuntimeSourceAdapter[];
+  /** STEP reader strategy used for STEP exports. */
+  stepStreaming?: StepStreamingMode;
+  /** Whether STEP loading should also produce mesh evidence. Defaults to true. */
+  mesh?: boolean;
+  /** Linear tolerance used while meshing exact BRep evidence. */
+  meshLinearTolerance?: number;
+  /** Angular tolerance in degrees used while meshing exact BRep evidence. */
+  meshAngularToleranceDegrees?: number;
+};
+/**
+ * Options accepted by {@link import('./load-model.js').loadModel}.
+ *
+ * @public
+ */
+type LoadModelOptions<Code extends Record<string, string> = Record<string, string>> = LoadModelSourceOptions | LoadModelCodeOptions<Code> | LoadModelFileOptions;
+/**
+ * Function shape used by GeoSpec runners to provide model loading inside VM
+ * executed test files.
+ *
+ * @public
+ */
+type GeoSpecModelLoader = <Code extends Record<string, string> = Record<string, string>>(options: LoadModelOptions<Code>) => Promise<GeoSpecSubject>;
+/** A configured loader whose shared runtime can be released with its owner. @public */
+type ManagedGeoSpecModelLoader = GeoSpecModelLoader & {
+  dispose(): Promise<void>;
+};
+/**
+ * Defaults accepted by {@link import('./load-model.js').createModelLoader}.
+ *
+ * @public
+ */
+type CreateModelLoaderOptions = {
+  /** Initialized compiled engine supplied by the host, never selected by an authored spec. */
+  engine: GeoSpecNativeModelEngine;
+  /** Rooted host reader for direct filesystem or URL sources. */
+  readSource?: GeoSpecNativeSourceReader;
+  /** Geometry format to export when an individual call does not specify one. */
+  format?: GeoSpecModelFormat;
+  /** Runtime client or lazy runtime factory. */
+  runtime?: GeoSpecRuntimeClient | GeoSpecRuntimeClientFactory;
+  /** Source-specific runtime adapters, e.g. host-provided GPL-isolated kernels. */
+  sourceAdapters?: readonly GeoSpecRuntimeSourceAdapter[];
+  /** Project root used by runtime integrations. */
+  projectPath?: string;
+  /** STEP reader strategy used for STEP sources or exports. */
+  stepStreaming?: StepStreamingMode;
+  /** Whether STEP loading should also produce mesh evidence. Defaults to true. */
+  mesh?: boolean;
+  /** Linear tolerance used while meshing exact BRep evidence. */
+  meshLinearTolerance?: number;
+  /** Angular tolerance in degrees used while meshing exact BRep evidence. */
+  meshAngularToleranceDegrees?: number;
+};
+//#endregion
+export { CreateModelLoaderOptions, GeoSpecModelFormat, GeoSpecModelLoader, GeoSpecRuntimeClient, GeoSpecRuntimeClientFactory, GeoSpecRuntimeSourceAdapter, LoadModelCodeOptions, LoadModelFileOptions, LoadModelOptions, LoadModelSourceOptions, ManagedGeoSpecModelLoader, MeshBufferSource, MeshSource };

package/dist/runner/collector.d.mts

@@ -0,0 +1,62 @@
+import { GeometryDiagnostic } from "../mesh/types.mjs";
+import { GeoSpecMatcher, GeoSpecTestCase } from "./types.mjs";
+import { GeoSpecAssertionClientOptions } from "../assertion-client/client.mjs";
+import "../assertion-client/index.mjs";
+import { GeoSpecTestNamePattern } from "./filter.mjs";
+//#region src/runner/collector.d.ts
+type GeoSpecTestFunction = () => unknown | PromiseLike<unknown>;
+/**
+ * Collects suites, tests, assertions, and async completion state for one
+ * GeoSpec module execution.
+ *
+ * @public
+ */
+type GeoSpecCollector = {
+  tests: GeoSpecTestCase[];
+  describe(name: string, function_: GeoSpecTestFunction): void;
+  describeSkip(name: string, _function?: GeoSpecTestFunction): void;
+  it(name: string, function_: GeoSpecTestFunction): void;
+  itSkip(name: string, _function?: GeoSpecTestFunction): void;
+  expectGeo(subject: unknown): GeoSpecMatcher;
+  waitForCompletion(testTimeout?: number, testNamePattern?: GeoSpecTestNamePattern): Promise<void>;
+};
+/** Per-module collector configuration; native subject/engine lifetime stays with the host. @public */
+type GeoSpecCollectorOptions = {
+  matcherWallBackstop?: number;
+  forensic?: boolean;
+  nativeAssertions: GeoSpecAssertionClientOptions;
+};
+/**
+ * Assertion error thrown by GeoSpec matchers when an expectation does not hold.
+ *
+ * Runner, CLI, and tool adapters unwrap this error to preserve structured
+ * diagnostics instead of collapsing them into a single string.
+ *
+ * @public
+ */
+declare class GeoSpecAssertionError extends Error {
+  readonly diagnostics: readonly GeometryDiagnostic[];
+  constructor(diagnostics: readonly GeometryDiagnostic[]);
+}
+/**
+ * Create the collector used by the embedded GeoSpec runner.
+ *
+ * @param options - The native assertion client configuration for this module.
+ * @returns A fresh collector whose matchers evaluate through the native engine.
+ * @public
+ */
+declare function createCollector(options: GeoSpecCollectorOptions): GeoSpecCollector;
+/**
+ * Clear runner globals after a module finishes.
+ */
+/** @public */
+declare const clearCollectorGlobals: () => void;
+/**
+ * Install a collector into the current JavaScript global scope.
+ *
+ * @param collector - Collector for the active run.
+ */
+/** @public */
+declare const installCollector: (collector: GeoSpecCollector) => void;
+//#endregion
+export { GeoSpecAssertionError, GeoSpecCollector, GeoSpecCollectorOptions, clearCollectorGlobals, createCollector, installCollector };

package/dist/runner/collector.mjs

@@ -0,0 +1,2 @@
+import{resolveGeoSpecSubject as e}from"../model/subject.mjs";import{GeoSpecAssertionError as t,createGeoSpecAssertionClient as n,createGeoSpecMatcherMethods as r}from"../assertion-client/client.mjs";import{diagnosticForTransport as i,geometryDiagnosticSchema as a}from"../model/errors.mjs";import{matchesGeoSpecTestName as o}from"./filter.mjs";const s=`__GEOSPEC_COLLECTOR__`,c=globalThis,l=e=>typeof e==`object`&&!!e&&`then`in e&&typeof e.then==`function`;var u=class extends Error{diagnostics;constructor(e){super(e.map(e=>e.message).join(`
+`)||`GeoSpec assertion failed.`),this.name=`GeoSpecAssertionError`,this.diagnostics=Object.freeze([...e])}};const d=e=>{if(e instanceof u)return[...e.diagnostics];if(typeof e==`object`&&e&&Reflect.get(e,`name`)===`GeoSpecModelLoadError`){let t=Reflect.get(e,`diagnostics`);if(Array.isArray(t)&&t.length>0)try{return t.map(e=>i(f(e)))}catch{}}let t=typeof e==`object`&&e&&typeof Reflect.get(e,`message`)==`string`?String(Reflect.get(e,`message`)):String(e),{details:n}=i({code:`TEST_FAILED`,severity:`error`,message:t,details:e});return t.includes(`model.volume is not a function`)?[{code:`GEOSPEC_SUBJECT_API_MISUSE`,severity:`error`,message:`GeoSpec GeometrySubject does not expose model.volume().`,suggestion:`Use expectGeo(model).toHaveVolume({ value, tolerance }) instead of reading model.volume().`,details:n}]:/Cannot read properties of undefined \(reading 'bounds'\)/u.test(t)?[{code:`GEOSPEC_SUBJECT_API_MISUSE`,severity:`error`,message:`GeoSpec GeometrySubject does not expose model.boundingBox.bounds.`,suggestion:`Use expectGeo(model).toHaveBoundingBox({ min, max, size, center, tolerance }) instead of reading model.boundingBox.`,details:n}]:[{code:`TEST_FAILED`,severity:`error`,message:t,details:n}]},f=e=>a.parse(e),p=(e,t)=>{if(e.passed=t.length===0,e.diagnostics=t,t.length>0)throw new u(t);return e};var m=class extends Error{};const h=async(e,t)=>{if(t===void 0)return e;let n;try{return await Promise.race([e,new Promise((e,r)=>{n=setTimeout(()=>{r(new m(`GeoSpec test timed out after ${t}ms.`))},t)})])}finally{n!==void 0&&clearTimeout(n)}},g=(e,t)=>{for(let n of e)n.status===`rejected`&&t(n.reason)},_=()=>{let e=c[s];if(!v(e))throw Error(`GeoSpec collector is not active. Run the module through runGeoSpecModule().`);return e},v=e=>typeof e==`object`&&!!e&&`describe`in e&&`it`in e&&`expectGeo`in e&&`tests`in e,y=e=>typeof e==`object`&&!!e&&`suite`in e&&`name`in e&&`assertions`in e;function b(a){let s=n(a.nativeAssertions),c=[],m=[],_=[],v=[],b=new WeakSet,x,S=!1,C=(e,t)=>{_.push((async()=>{try{await e}catch(e){t.onError(e)}finally{t.onFinally()}})())},w=e=>{m.push({ordinal:m.length,suite:[...c],name:e,assertions:[],status:`skipped`,diagnostics:[]})},T=n=>{if(!y(x))throw Error(`expectGeo() must be called inside it().`);let r={kind:n.kind,subject:null,expected:n.expected};x.assertions.push(r);let o=performance.now();try{let o=e(n.subject,a.nativeAssertions.engine);r.subject=o.identity,o.load!==void 0&&(r.loadId=o.load.loadId);let c=s.expectGeo(o.identity),l=(n.polarity===`negative`?c.not:c)[n.matcher],u;try{u=l(...n.arguments)}catch(e){if(!(e instanceof t))throw e;u=e.report}if(r.report=u,u.status===`passed`)return p(r,[]);let d=u.diagnostics.map(e=>i(f(e)));return p(r,d.length>0?d:[{code:`GEOSPEC_NATIVE_ASSERTION_FAILED`,severity:`error`,message:`Native claim '${u.claimId}' ended with status '${u.status}'.`,details:{claimId:u.claimId,status:u.status}}])}catch(e){throw e instanceof u&&r.report!==void 0&&b.add(e),r.passed=!1,r.diagnostics??=d(e),e}finally{r.durationMs=performance.now()-o}};return{describe(e,t){c.push(e);try{let n=t();if(l(n)){let t=[...c];C(n,{onError(n){m.push({ordinal:m.length,suite:t,name:e,assertions:[],status:`failed`,diagnostics:d(n)})},onFinally(){c.pop()}});return}}catch(t){m.push({ordinal:m.length,suite:[...c],name:e,assertions:[],status:`failed`,diagnostics:d(t)})}c.pop()},describeSkip(e){w(e)},it(e,t){let n={ordinal:m.length,suite:[...c],name:e,assertions:[],status:`not-run`,diagnostics:[]};m.push(n),v.push({test:n,function_:t})},itSkip(e){w(e)},expectGeo(e){return Object.assign(r({invoke:T,polarity:`positive`,subject:e}),{not:r({invoke:T,polarity:`negative`,subject:e})})},async waitForCompletion(e,t){if(S)return;S=!0;let n=Promise.allSettled(_);try{await h(n,e)}catch(e){throw await n,e}for(let n of v){if(!o(n.test,t))continue;let r=x;x=n.test,n.test.status=`passed`;let i=performance.now(),a=[],s=e=>{a.some(t=>Object.is(t,e))||a.push(e)};try{let t;try{t=Promise.resolve(n.function_()),await h(t,e)}catch(e){s(e)}if(t!==void 0&&g(await Promise.allSettled([t]),s),a.length>0||n.test.assertions.some(e=>e.passed===!1)){n.test.status=`failed`;for(let e of a)n.test.diagnostics.push(...d(e));let{assertions:e}=n.test;if(!(a.some(e=>!(e instanceof u)||!b.has(e))||e.some(e=>e.passed===!1&&(e.report===void 0||e.report.status===`invalid`||e.report.status===`engine-error`)))){let t=e.map(e=>e.report?.status);n.test.status=t.includes(`failed`)?`failed`:t.some(e=>e!==void 0&&e!==`passed`&&e!==`unsupported`)?`inconclusive`:t.includes(`unsupported`)?`unsupported`:`failed`}}}finally{x=r,n.test.durationMs=performance.now()-i}}},tests:m}}const x=()=>{Reflect.deleteProperty(c,s)},S=e=>{c[s]=e};export{u as GeoSpecAssertionError,x as clearCollectorGlobals,s as collectorGlobalKey,b as createCollector,_ as getCollector,S as installCollector};

package/dist/runner/discovery.d.mts

@@ -0,0 +1,93 @@
+//#region src/runner/discovery.d.ts
+/**
+ * Default file globs used by GeoSpec test discovery.
+ *
+ * @public
+ */
+declare const defaultGeoSpecInclude: readonly ["**/*.geospec.{ts,js}"];
+/**
+ * Directories skipped by recursive GeoSpec discovery unless callers provide
+ * their own ignored-directory list.
+ *
+ * @public
+ */
+declare const defaultGeoSpecIgnoredDirectories: readonly [".git", "node_modules", "dist", "coverage", ".tau/cache", ".tau/artifacts", ".tau/transcripts"];
+/**
+ * File kind returned by a GeoSpec discovery filesystem.
+ *
+ * @public
+ */
+type GeoSpecDiscoveryFileKind = 'file' | 'directory';
+/**
+ * Minimal stat object required for recursive GeoSpec test discovery.
+ *
+ * @public
+ */
+type GeoSpecDiscoveryFileStat = {
+  kind: GeoSpecDiscoveryFileKind;
+};
+/**
+ * Minimal filesystem contract used by GeoSpec test discovery.
+ *
+ * Browser workers, Node CLI hosts, and embedded runners adapt their native
+ * filesystem APIs to this shape so discovery has one shared behavior.
+ *
+ * @public
+ */
+type GeoSpecDiscoveryFileSystem = {
+  readdir(path: string): Promise<readonly string[]>;
+  stat(path: string): Promise<GeoSpecDiscoveryFileStat>;
+};
+/**
+ * Options for recursive GeoSpec test discovery.
+ *
+ * `files` accepts either exact `*.geospec.ts` / `*.geospec.js` files or
+ * directory roots. When omitted, discovery starts at `projectPath`.
+ *
+ * `include` and `exclude` are Vitest-style file globs applied to
+ * project-relative GeoSpec paths after `files` roots have been expanded.
+ *
+ * @public
+ */
+type DiscoverGeoSpecFilesOptions = {
+  filesystem: GeoSpecDiscoveryFileSystem;
+  projectPath: string;
+  files?: readonly string[];
+  include?: readonly string[];
+  exclude?: readonly string[];
+  ignoredDirectories?: readonly string[];
+};
+/**
+ * Result returned by recursive GeoSpec test discovery.
+ *
+ * `files` are project-relative, sorted, and de-duplicated. `unmatchedRoots`
+ * contains requested file or directory roots that did not select any GeoSpec
+ * files.
+ *
+ * @public
+ */
+type GeoSpecDiscoveryResult = {
+  files: string[];
+  unmatchedRoots: string[];
+};
+/**
+ * Return true when a project-relative path names a GeoSpec test file.
+ *
+ * @param path - Project-relative path to inspect.
+ * @returns True when the path ends with `.geospec.ts` or `.geospec.js`.
+ * @public
+ */
+declare const isGeoSpecTestFile: (path: string) => boolean;
+/**
+ * Discover GeoSpec test files from exact files or directory roots.
+ *
+ * The returned `files` are project-relative paths suitable for
+ * `runGeoSpecModule` and runner factory APIs.
+ *
+ * @param options - Discovery options containing a filesystem adapter and project roots.
+ * @returns Sorted, de-duplicated project-relative GeoSpec files plus unmatched roots.
+ * @public
+ */
+declare const discoverGeoSpecFiles: (options: DiscoverGeoSpecFilesOptions) => Promise<GeoSpecDiscoveryResult>;
+//#endregion
+export { DiscoverGeoSpecFilesOptions, GeoSpecDiscoveryFileKind, GeoSpecDiscoveryFileStat, GeoSpecDiscoveryFileSystem, GeoSpecDiscoveryResult, defaultGeoSpecIgnoredDirectories, defaultGeoSpecInclude, discoverGeoSpecFiles, isGeoSpecTestFile };

package/dist/runner/discovery.mjs

@@ -0,0 +1 @@
+import{assertRootedPath as e}from"@taucad/runtime/kernel";const t=[`**/*.geospec.{ts,js}`],n=[`.git`,`node_modules`,`dist`,`coverage`,`.tau/cache`,`.tau/artifacts`,`.tau/transcripts`],r=/\.geospec\.(?:ts|js)$/u,i=e=>e.replaceAll(`\\`,`/`).replaceAll(/\/+/gu,`/`).replace(/^\.\//u,``),a=e=>{let t=i(e);return!t||t===`.`?``:t===`/`?t:t.replace(/\/$/u,``)},o=(t,n)=>{let r=e(t);return r===``?n:n===``?r:`${n.replace(/\/$/u,``)}/${r}`},s=(e,t)=>{let n=i(e).replace(/\/$/u,``);if(t===``)return n;let r=t.endsWith(`/`)?t:`${t}/`;return n===t?``:n.startsWith(r)?n.slice(r.length):n},c=e=>e.replaceAll(/[|\\{}()[\]^$+?.]/gu,String.raw`\$&`),l=e=>{let t=i(e),n=`^`;for(let e=0;e<t.length;){let r=t[e];if(r===void 0)break;let i=t[e+1];if(r===`*`&&i===`*`){t[e+2]===`/`?(n+=String.raw`(?:.*\/)?`,e+=3):(n+=`.*`,e+=2);continue}if(r===`*`){n+=`[^/]*`,e+=1;continue}if(r===`?`){n+=`[^/]`,e+=1;continue}if(r===`{`){let r=t.indexOf(`}`,e+1);if(r!==-1){let i=t.slice(e+1,r).split(`,`).map(e=>c(e));n+=`(?:${i.join(`|`)})`,e=r+1;continue}}n+=r===`/`?String.raw`\/`:c(r),e+=1}return RegExp(`${n}$`,`u`)},u=(e,t)=>l(t).test(i(e)),d=(e,t)=>t.some(t=>u(e,t)),f=(e,t)=>{let n=i(e).replace(/\/$/u,``),r=n.split(`/`).at(-1)??n;return t.has(n)||t.has(r)},p=e=>{if(typeof e!=`object`||!e)return!1;let t=`code`in e?e.code:void 0,n=`name`in e?e.name:void 0,r=e instanceof Error?e.message:``;return t===`ENOENT`||t===`ENOTDIR`||n===`NotFoundError`||r.startsWith(`ENOENT:`)||r.startsWith(`ENOTDIR:`)},m=e=>r.test(i(e)),h=async e=>{let t=await e.filesystem.readdir(e.directoryPath),n=[];for(let r of t){let t=e.directoryPath===``?r:`${e.directoryPath}/${r}`,i=s(t,e.projectPath);if((await e.filesystem.stat(t)).kind===`directory`){f(i,e.ignoredDirectories)||n.push(t);continue}m(i)&&e.selectedFiles.add(i)}n.sort((e,t)=>e.localeCompare(t));for(let t of n)await h({...e,directoryPath:t})},g=async e=>{let t=new Set,n=o(e.root,e.projectPath),r;try{r=await e.filesystem.stat(n)}catch(e){if(p(e))return[];throw e}if(r.kind===`file`){let r=s(n,e.projectPath);return m(r)&&t.add(r),[...t]}let i=s(n,e.projectPath);return i&&f(i,e.ignoredDirectories)?[]:(await h({filesystem:e.filesystem,directoryPath:n,projectPath:e.projectPath,ignoredDirectories:e.ignoredDirectories,selectedFiles:t}),[...t])},_=async e=>{let r=a(e.projectPath),o=e.include&&e.include.length>0?e.include:t,s=e.exclude??[],c=new Set(e.ignoredDirectories??n),l=e.files&&e.files.length>0?e.files:[``],u=new Set,f=[];for(let t of l){let n=await g({filesystem:e.filesystem,projectPath:r,root:t,ignoredDirectories:c});if(n.length===0){f.push(i(t)||`.`);continue}for(let e of n)u.add(e)}return{files:[...u].filter(e=>d(e,o)&&!d(e,s)).sort((e,t)=>e.localeCompare(t)),unmatchedRoots:f}};export{n as defaultGeoSpecIgnoredDirectories,t as defaultGeoSpecInclude,_ as discoverGeoSpecFiles,m as isGeoSpecTestFile};

package/dist/runner/filter.d.mts

@@ -0,0 +1,50 @@
+import { GeoSpecTestCase } from "./types.mjs";
+import { VmIssue } from "@taucad/esbuild/vm";
+//#region src/runner/filter.d.ts
+/**
+ * Compiled Vitest-style test-name pattern used by a GeoSpec run.
+ *
+ * @public
+ */
+type GeoSpecTestNamePattern = RegExp;
+/**
+ * Compile a Vitest-style test-name pattern once for a GeoSpec run.
+ *
+ * String inputs are JavaScript regular expression sources matched against the
+ * full `suite > test` name. `RegExp` inputs are used as-is.
+ *
+ * @param testNamePattern - Optional regex source or precompiled expression.
+ * @returns A compiled pattern or a structured issue when the source is invalid.
+ *
+ * @public
+ */
+declare const compileGeoSpecTestNamePattern: (testNamePattern: string | RegExp | undefined) => {
+  success: true;
+  pattern?: GeoSpecTestNamePattern;
+} | {
+  success: false;
+  issue: VmIssue;
+};
+/**
+ * Return true when a collected GeoSpec test matches the supplied compiled
+ * Vitest-style test-name pattern.
+ *
+ * @public
+ *
+ * @param test - collected test metadata.
+ * @param testNamePattern - optional compiled regex.
+ * @returns whether the test should be included.
+ */
+declare const matchesGeoSpecTestName: (test: Pick<GeoSpecTestCase, "suite" | "name">, testNamePattern: GeoSpecTestNamePattern | undefined) => boolean;
+/**
+ * Filter collected GeoSpec tests by compiled test-name pattern.
+ *
+ * @public
+ *
+ * @param tests - collected tests.
+ * @param testNamePattern - optional compiled regex.
+ * @returns tests that match the filter.
+ */
+declare const filterGeoSpecTests: (tests: readonly GeoSpecTestCase[], testNamePattern: GeoSpecTestNamePattern | undefined) => GeoSpecTestCase[];
+//#endregion
+export { GeoSpecTestNamePattern, compileGeoSpecTestNamePattern, filterGeoSpecTests, matchesGeoSpecTestName };

package/dist/runner/filter.mjs

@@ -0,0 +1 @@
+const e=e=>[...e.suite,e.name].join(` > `),t=e=>{if(e===void 0||typeof e==`string`&&e.trim()===``)return{success:!0};if(e instanceof RegExp)return{success:!0,pattern:e};try{return{success:!0,pattern:new RegExp(e,`u`)}}catch(t){return{success:!1,issue:{code:`INVALID_GEOSPEC_TEST_NAME_PATTERN`,message:`testNamePattern is not a valid JavaScript regular expression.`,severity:`error`,type:`runtime`,details:{testNamePattern:e,reason:t instanceof Error?t.message:String(t)}}}}},n=(t,n)=>!n||(n.lastIndex=0,n.test(e(t))),r=(e,t)=>e.filter(e=>n(e,t));export{t as compileGeoSpecTestNamePattern,r as filterGeoSpecTests,n as matchesGeoSpecTestName};

package/dist/runner/index.d.mts

@@ -0,0 +1,6 @@
+import { GeoSpecAssemblyOccurrenceExpectation, GeoSpecAssemblyOccurrencesExpectation, GeoSpecAssertion, GeoSpecAxisExpectation, GeoSpecBoundingBoxExpectation, GeoSpecCenterOfMassExpectation, GeoSpecChamferFeatureExpectation, GeoSpecCircularHoleExpectation, GeoSpecCircularHolePatternExpectation, GeoSpecComponentInterferenceAllowance, GeoSpecComponentInterferenceExpectation, GeoSpecComponentInterferencePairExpectation, GeoSpecConnectedComponentsExpectation, GeoSpecCylindricalFaceExpectation, GeoSpecFilletFeatureExpectation, GeoSpecGeometrySelector, GeoSpecMassExpectation, GeoSpecMatcher, GeoSpecMeshIntegrityExpectation, GeoSpecMinimumWallThicknessExpectation, GeoSpecModuleBundleCache, GeoSpecNumericExpectation, GeoSpecPlanarFaceExpectation, GeoSpecPointExpectation, GeoSpecProductStructureExpectation, GeoSpecRunFailure, GeoSpecRunResult, GeoSpecRunSuccess, GeoSpecSpatialRelationshipExpectation, GeoSpecSpatialRelationshipsExpectation, GeoSpecStepUnitsExpectation, GeoSpecSurfaceAreaExpectation, GeoSpecTestCase, GeoSpecTestStatus, GeoSpecTopologyCountsExpectation, GeoSpecValidBrepExpectation, GeoSpecVolumeExpectation, RunGeoSpecModuleOptions } from "./types.mjs";
+import { GeoSpecTestNamePattern, compileGeoSpecTestNamePattern, filterGeoSpecTests, matchesGeoSpecTestName } from "./filter.mjs";
+import { GeoSpecAssertionError, GeoSpecCollector, GeoSpecCollectorOptions, clearCollectorGlobals, createCollector, installCollector } from "./collector.mjs";
+import { DiscoverGeoSpecFilesOptions, GeoSpecDiscoveryFileKind, GeoSpecDiscoveryFileStat, GeoSpecDiscoveryFileSystem, GeoSpecDiscoveryResult, defaultGeoSpecIgnoredDirectories, defaultGeoSpecInclude, discoverGeoSpecFiles, isGeoSpecTestFile } from "./discovery.mjs";
+import { runGeoSpecModule } from "./run-geospec-module.mjs";
+export { type DiscoverGeoSpecFilesOptions, type GeoSpecAssemblyOccurrenceExpectation, type GeoSpecAssemblyOccurrencesExpectation, type GeoSpecAssertion, GeoSpecAssertionError, type GeoSpecAxisExpectation, type GeoSpecBoundingBoxExpectation, type GeoSpecCenterOfMassExpectation, type GeoSpecChamferFeatureExpectation, type GeoSpecCircularHoleExpectation, type GeoSpecCircularHolePatternExpectation, type GeoSpecCollector, type GeoSpecCollectorOptions, type GeoSpecComponentInterferenceAllowance, type GeoSpecComponentInterferenceExpectation, type GeoSpecComponentInterferencePairExpectation, type GeoSpecConnectedComponentsExpectation, type GeoSpecCylindricalFaceExpectation, type GeoSpecDiscoveryFileKind, type GeoSpecDiscoveryFileStat, type GeoSpecDiscoveryFileSystem, type GeoSpecDiscoveryResult, type GeoSpecFilletFeatureExpectation, type GeoSpecGeometrySelector, type GeoSpecMassExpectation, type GeoSpecMatcher, type GeoSpecMeshIntegrityExpectation, type GeoSpecMinimumWallThicknessExpectation, type GeoSpecModuleBundleCache, type GeoSpecNumericExpectation, type GeoSpecPlanarFaceExpectation, type GeoSpecPointExpectation, type GeoSpecProductStructureExpectation, type GeoSpecRunFailure, type GeoSpecRunResult, type GeoSpecRunSuccess, type GeoSpecSpatialRelationshipExpectation, type GeoSpecSpatialRelationshipsExpectation, type GeoSpecStepUnitsExpectation, type GeoSpecSurfaceAreaExpectation, type GeoSpecTestCase, type GeoSpecTestNamePattern, type GeoSpecTestStatus, type GeoSpecTopologyCountsExpectation, type GeoSpecValidBrepExpectation, type GeoSpecVolumeExpectation, type RunGeoSpecModuleOptions, clearCollectorGlobals, compileGeoSpecTestNamePattern, createCollector, defaultGeoSpecIgnoredDirectories, defaultGeoSpecInclude, discoverGeoSpecFiles, filterGeoSpecTests, installCollector, isGeoSpecTestFile, matchesGeoSpecTestName, runGeoSpecModule };

package/dist/runner/index.mjs

@@ -0,0 +1 @@
+import{compileGeoSpecTestNamePattern as e,filterGeoSpecTests as t,matchesGeoSpecTestName as n}from"./filter.mjs";import{GeoSpecAssertionError as r,clearCollectorGlobals as i,createCollector as a,installCollector as o}from"./collector.mjs";import{defaultGeoSpecIgnoredDirectories as s,defaultGeoSpecInclude as c,discoverGeoSpecFiles as l,isGeoSpecTestFile as u}from"./discovery.mjs";import{runGeoSpecModule as d}from"./run-geospec-module.mjs";export{r as GeoSpecAssertionError,i as clearCollectorGlobals,e as compileGeoSpecTestNamePattern,a as createCollector,s as defaultGeoSpecIgnoredDirectories,c as defaultGeoSpecInclude,l as discoverGeoSpecFiles,t as filterGeoSpecTests,o as installCollector,u as isGeoSpecTestFile,n as matchesGeoSpecTestName,d as runGeoSpecModule};

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

@@ -0,0 +1,4 @@
+import { CreateGeoSpecNativeModelLoaderOptions, GeoSpecNativeLoadModelOptions, GeoSpecNativeModelEngine, GeoSpecNativeModelLoader, GeoSpecNativeModelResource, GeoSpecNativeModelSubject, GeoSpecNativeSourceReader, ManagedGeoSpecNativeModelLoader, createGeoSpecNativeModelLoader } from "../../model/native-model-loader.mjs";
+import { GeoSpecNativeRunnerAssertions, GeoSpecNativeRunnerOptions, createNativeGeoSpecRunner } from "./native-serial-runner.mjs";
+import { allocateNativePoolGrants } from "./native-pool-grants.mjs";
+export { type CreateGeoSpecNativeModelLoaderOptions, type GeoSpecNativeLoadModelOptions, type GeoSpecNativeModelEngine, type GeoSpecNativeModelLoader, type GeoSpecNativeModelResource, type GeoSpecNativeModelSubject, type GeoSpecNativeRunnerAssertions, type GeoSpecNativeRunnerOptions, type GeoSpecNativeSourceReader, type ManagedGeoSpecNativeModelLoader, allocateNativePoolGrants, createGeoSpecNativeModelLoader, createNativeGeoSpecRunner };

package/dist/runner/native/index.mjs

@@ -0,0 +1 @@
+import{createGeoSpecNativeModelLoader as e}from"../../model/native-model-loader.mjs";import{createNativeGeoSpecRunner as t}from"./native-serial-runner.mjs";import{allocateNativePoolGrants as n}from"./native-pool-grants.mjs";export{n as allocateNativePoolGrants,e as createGeoSpecNativeModelLoader,t as createNativeGeoSpecRunner};