geospec 0.0.0 → 0.1.0-beta.3

package/dist/model/load-model.d.mts

@@ -0,0 +1,25 @@
+import { GeoSpecSubject } from "./subject.mjs";
+import { CreateModelLoaderOptions, LoadModelOptions, ManagedGeoSpecModelLoader } from "./types.mjs";
+//#region src/model/load-model.d.ts
+/**
+ * Load a CAD model into GeoSpec evidence.
+ *
+ * This is the authoring declaration: a GeoSpec runner replaces it with the
+ * host's native model loader. Called outside a runner it always throws.
+ *
+ * @param _options - Source, code, or file model load options.
+ * @returns A GeoSpec geometry subject ready for `expectGeo`.
+ * @throws {@link GeoSpecModelLoadError} with `GEOSPEC_MODEL_LOADER_UNAVAILABLE` when no runner is active.
+ * @public
+ */
+declare function loadModel<Code extends Record<string, string> = Record<string, string>>(_options: LoadModelOptions<Code>): Promise<GeoSpecSubject>;
+/**
+ * Create a {@link loadModel} function over a host-supplied compiled engine.
+ *
+ * @param defaults - The compiled engine plus model loading defaults.
+ * @returns A configured model loader whose subjects are released by `dispose()`.
+ * @public
+ */
+declare const createModelLoader: (defaults: CreateModelLoaderOptions) => ManagedGeoSpecModelLoader;
+//#endregion
+export { createModelLoader, loadModel };

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,142 @@
+import { GeoSpecLoadRegion, 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;
+  /** Authored default work-unit budget for claims on this subject. */
+  readonly workUnitLimit?: number;
+  /**
+   * The crop box the kernel applied before export. Present only on a cropped load: its subject is
+   * the region, never the whole model.
+   */
+  readonly region?: GeoSpecLoadRegion;
+  /**
+   * True when this load reused the run's earlier admission of identical inputs: the same file,
+   * code, parameters, format, tolerances, region and ingest options, with an unchanged source
+   * revision. No export or ingest ran for it; its artifacts and source revision are the earlier
+   * load's, and lineage still records it under its own load id.
+   */
+  readonly reused?: true;
+  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>;
+  /**
+   * The largest `loadModel` `workUnitLimit` a spec may author. Host policy: omitted uses
+   * `geoSpecMaximumWorkUnitLimit`, and a host provisioned for larger claims raises it.
+   */
+  readonly maximumWorkUnitLimit?: number;
+};
+/**
+ * Model loader injected into native VM runs.
+ *
+ * Direct `source` loads read their source again on every call and the engine
+ * digests those exact bytes; bytes equal to an admitted subject's reuse that
+ * subject by digest, length and descriptor, and edited bytes admit a new
+ * subject. Runtime loads are coalesced per release scope (one run): a load
+ * whose file, inline code, project path, parameters, format, tolerances,
+ * region and ingest options equal an earlier successful load's reuses that
+ * admission without exporting or ingesting again. A file load is reused only
+ * while a Runtime source snapshot still matches the earlier load's complete
+ * source revision; otherwise, or when every owner of the earlier admission has
+ * released it, the load exports afresh. Failures are never reused.
+ *
+ * @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{geoSpecAuthoredWorkUnitLimitProblem as e,resolveGeoSpecMaximumWorkUnitLimit as t}from"../engine/client.mjs";import{bindRawSubjectResidency as n}from"./subject.mjs";import{GeoSpecModelLoadError as r}from"./errors.mjs";import{resolveRuntimeExportIntent as i}from"./export-intent.mjs";import{sha256Bytes as a}from"@taucad/runtime/kernel";const o={canonicalProfile:`geospec-jcs-v1`,protocolVersion:3,registryVersion:5},s=new TextEncoder,c=new TextDecoder(`utf-8`,{fatal:!0}),l=new Set([`glb`,`step`,`stp`]),u=new WeakMap,d=16777216,f=e=>e instanceof Error&&`code`in e&&e.code===`limit-exceeded`&&e.message===`Engine exceeds the configured retained subject count.`,p=e=>{let t=u.get(e);if(t!==void 0)return t;let n=y(e.processRequest(_({...o,method:`initialize`,requestId:`configuration`})),`initialize response`),r=v(n.result,`initialize result`);if(n.requestId!==`configuration`||r.protocolVersion!==3||r.registryVersion!==5||r.canonicalProfile!==`geospec-jcs-v1`)throw TypeError(`Native GeoSpec residency requires a compatible initialize profile.`);let i=v(r.configuration,`initialize configuration`),a=v(i.binaryAdmissionLimits,`binary admission limits`),s=[a.maxSubjectBytes,a.maxTotalBinaryBytes].map(e=>{if(typeof e!=`number`||!Number.isSafeInteger(e)||e<=0)throw TypeError(`Native GeoSpec residency requires safe positive binary admission limits.`);return e}),c={inputs:new Map,resident:new Map,binaryLimit:Math.max(...s),binaryBytes:0,descriptorBytes:0};return u.set(e,c),c},m=e=>new r(e),h=e=>({code:e.code,severity:`error`,message:e.message,suggestion:e.suggestion,...e.details===void 0?{}:{details:e.details}}),g=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.`}),_=e=>s.encode(JSON.stringify(e)),v=(e,t)=>{if(typeof e!=`object`||!e||Array.isArray(e))throw TypeError(`Native GeoSpec returned a non-object ${t}.`);return e},y=(e,t)=>v(JSON.parse(c.decode(e)),t),b=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 m([h({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 m([h({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().`})])},x=e=>`code`in e?{files:e.code,entry:e.file}:{path:e.file},S=(e,t)=>{let n=e.format??t??`glb`;if(!l.has(n))throw m([h({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},C=(e,t)=>{let{routesFor:n,bestRouteFor:r}=e;if(typeof n==`function`)return n.call(e,t);let i=typeof r==`function`?r.call(e,t):void 0;return i===void 0?[]:[i]},w=async(e,t)=>{if(typeof e.describe==`function`)try{let{kernelId:n}=await e.describe({source:x(t)});return typeof n==`string`&&n.length>0?n:void 0}catch{return}},T=e=>{if(e===null||typeof e==`boolean`||typeof e==`string`)return JSON.stringify(e);if(typeof e==`number`)return Number.isFinite(e)?JSON.stringify(e):void 0;if(Array.isArray(e)){let t=e.map(e=>T(e));return t.includes(void 0)?void 0:`[${t.join(`,`)}]`}if(typeof e==`object`&&Object.getPrototypeOf(e)===Object.prototype){let t=Object.entries(e).filter(([,e])=>e!==void 0).sort(([e],[t])=>e<t?-1:1).map(([e,t])=>[e,T(t)]);return t.some(([,e])=>e===void 0)?void 0:`{${t.map(([e,t])=>`${JSON.stringify(e)}:${t}`).join(`,`)}}`}},E=e=>Array.isArray(e)&&e.length===3&&e.every(e=>typeof e==`number`&&Number.isFinite(e)),D=e=>{if(e===void 0)return;let t=typeof e==`object`&&e?e:{},{min:n,max:r}=t;return E(n)&&E(r)&&Object.keys(t).every(e=>e===`min`||e===`max`)&&n.every((e,t)=>e<r[t])?void 0:m([h({code:`GEOSPEC_MODEL_OPTION_INVALID`,message:`loadModel region must be { min: [x, y, z], max: [x, y, z] } in millimetres with every min axis below its max axis.`,suggestion:`Pass finite millimetre corners of the box to check, for example { min: [0, 0, 0], max: [40, 40, 60] }.`,details:{option:`region`,region:structuredClone(e)}})])},O=({min:e,max:t})=>({min:[e[0],e[1],e[2]],max:[t[0],t[1],t[2]]}),k=(e,t)=>{let n=t.sourceRevision?.files??Object.fromEntries(t.data.files.map(({path:e,sha256:t})=>[e,`sha256:${t}`]));return(t.sourceRevision?.entry??t.data.entryPath)===e.entry&&Object.entries(n).every(([t,n])=>n===`missing`||e.files[t]===n)&&Object.entries(e.files).every(([e,t])=>t===`missing`?n[e]===void 0||n[e]===`missing`:n[e]===t)},A=r=>{let s=0,c=t(r.maximumWorkUnitLimit),l=new Map,E=new Map,A=0,j=new Set,M=new Map,N=new Set,P=new Map,F=e=>(s+=1,`geospec-native-model:${e}:${s}`),I=e=>(e.sourceAdapters??r.sourceAdapters)?.find(t=>t.extensions.some(t=>e.file.endsWith(t))),L=async e=>{let t=e.runtime??r.runtime;if(typeof t==`function`){let e=P.get(t);e===void 0&&(e=t(),P.set(t,e));let n=await e;return N.add(n),n}if(t!==void 0)return t;let n=I(e);if(n!==void 0){let t=await n.createRuntime({file:e.file,...(e.projectPath??r.projectPath)===void 0?{}:{projectPath:e.projectPath??r.projectPath}});return N.add(t),t}throw m([h({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}})])},R=e=>{r.engine.releaseSubject(_({...o,method:`releaseSubject`,requestId:F(`release`),subjectHandle:e}))},z=(e,t)=>{let n=u.get(r.engine),i=n?.inputs.get(e);if(n!==void 0&&i!==void 0&&(i.cleanupPending?.(),delete i.cleanupPending,i.owners.has(t))){if(i.owners.size>1){i.owners.delete(t);return}i.handle!==void 0&&(R(i.handle),delete i.handle),i.owners.delete(t),n.resident.delete(e),n.inputs.delete(e),n.binaryBytes-=i.resources.reduce((e,t)=>e+t.byteLength,i.primary.byteLength),n.descriptorBytes-=i.request.byteLength}},B=e=>{for(let[t,n]of e.inputs)n.cleanupPending!==void 0&&(n.cleanupPending(),delete n.cleanupPending,delete n.handle,e.resident.delete(t))},V=()=>[...r.carried??[]].filter(([e])=>!l.has(e)),H=(e,t)=>{let n=e.format===`stp`?`step`:e.format,i=p(r.engine);B(i);let a=_({...o,method:`ingestSubject`,requestId:F(`ingest`),format:n,frame:{coordinateSystem:`z-up`,sourceUnit:n===`step`?`auto`:e.sourceUnit??`m`,outputUnit:`mm`},ingestOptions:e.ingestOptions??{},...e.diagnostics===void 0||e.diagnostics.length===0?{}:{diagnostics:e.diagnostics},primaryByteLength:e.primary.byteLength,resources:e.resources.map(({name:e,bytes:t})=>({name:e,byteLength:t.byteLength}))}),s=e.resources.reduce((e,{bytes:t})=>e+t.byteLength,e.primary.byteLength);if(!Number.isSafeInteger(s)||s>i.binaryLimit||a.byteLength>d)throw Object.assign(RangeError(`GeoSpec retained admission input exceeds its byte limit.`),{code:`limit-exceeded`});let c=(e,t)=>e.length===t.length&&e.every((e,n)=>e===t[n]),u={...y(a,`admission request`),requestId:``},m=[...i.inputs.values()].find(t=>{let n={...y(t.request,`retained request`),requestId:``};return JSON.stringify(n)===JSON.stringify(u)&&c(t.primary,e.primary)&&t.resources.length===e.resources.length&&t.resources.every((t,n)=>c(t,e.resources[n].bytes))});if(m===void 0&&(s>i.binaryLimit-i.binaryBytes||a.byteLength>d-i.descriptorBytes))throw Object.assign(RangeError(`GeoSpec live admission snapshots exceed their retained input byte limit.`),{code:`limit-exceeded`});let h=m??{request:Uint8Array.from(a),primary:Uint8Array.from(e.primary),resources:e.resources.map(({bytes:e})=>Uint8Array.from(e)),owners:new Set},g=()=>r.engine.ingestSubject(a,e.primary,e.resources.map(({bytes:e})=>e)),b;try{b=g()}catch(e){let t=V();if(!f(e))throw e;let n=!1;for(let[e,a]of t){let t=i.inputs.get(e);if(t===void 0)R(a),n=!0;else{let i=t.owners.size===1&&t.handle!==void 0;z(e,r.carried),n||=i}r.carried?.delete(e)}if(!n){let t=i.resident.entries().next().value;if(t===void 0)throw e;R(t[1].handle),delete t[1].handle,i.resident.delete(t[0])}b=g()}let x=y(b,`admission response`),S=v(x.result,`admission result`),{subjectHash:C}=v(S.subject,`admitted subject`);if(typeof C!=`string`||!/^[0-9a-f]{64}$/u.test(C))throw TypeError(`Native GeoSpec admission did not return a valid subjectHash.`);let w=y(r.engine.subjectHandle(_({...o,method:`subjectHandle`,requestId:F(`handle`),subjectHash:C})),`subject-handle response`),T=v(w.result,`subject-handle result`).subjectHandle;if(T===void 0)throw TypeError(`Native GeoSpec did not return a subject handle.`);let D=i.inputs.get(C),O=D??h;D===void 0&&(i.inputs.set(C,O),i.binaryBytes+=s,i.descriptorBytes+=O.request.byteLength);for(let e of t)O.owners.add(e),E.set(e,C);return O.handle=T,i.resident.delete(C),i.resident.set(C,O),l.set(C,O),{subjectHash:C}},U=e=>{let t=l.get(e);if(t===void 0)throw TypeError(`This subject is not admitted by the active GeoSpec host.`);let n=p(r.engine);if(B(n),t.handle===void 0){let i=()=>r.engine.ingestSubject(t.request,t.primary,t.resources),a;try{a=i()}catch(e){let t=n.resident.entries().next().value;if(!f(e)||t===void 0)throw e;R(t[1].handle),delete t[1].handle,n.resident.delete(t[0]),a=i()}let s=()=>{let t=v(y(r.engine.subjectHandle(_({...o,method:`subjectHandle`,requestId:F(`restore-handle`),subjectHash:e})),`restored handle`).result,`restored handle result`),n=v(t.subjectHandle,`restored subject handle`);if(n.subjectHash!==e)throw TypeError(`Native GeoSpec restored handle changed its subject identity.`);return n};try{if(v(v(y(a,`restored admission`).result,`restored result`).subject,`restored subject`).subjectHash!==e)throw TypeError(`Native GeoSpec restored admission changed its subject identity.`);t.handle=s()}catch(e){throw t.cleanupPending=()=>{try{R(s())}catch(t){throw AggregateError([e,t],`Native GeoSpec restored admission failed and cleanup remains pending.`,{cause:e})}},t.cleanupPending(),delete t.cleanupPending,e}}n.resident.delete(e),n.resident.set(e,t)},W=async(e,t)=>{let n=S(e,r.format),i=await b(e.source,r.readSource),o=await Promise.all((e.resources??[]).map(async({name:e,source:t})=>({name:e,bytes:await b(t,r.readSource),...typeof t==`string`?{sourcePath:t}:{}}))),s=await Promise.all([{name:e.path??e.name??`primary`,bytes:i,...typeof e.source==`string`?{sourcePath:e.source}:{}},...o].map(async({name:e,bytes:t,sourcePath:n})=>({name:e,sha256:await a(t),byteLength:t.byteLength,...n===void 0?{}:{sourcePath:n}})));return{...H({format:n,primary:i,resources:o,...e.ingestOptions===void 0?{}:{ingestOptions:e.ingestOptions},...e.sourceUnit===void 0?{}:{sourceUnit:e.sourceUnit}},t),load:{loadId:``,status:`complete`,format:n,parameters:e.parameters??{},ingestOptions:e.ingestOptions??{},...typeof e.source==`string`?{sourcePath:e.source}:{},...e.workUnitLimit===void 0?{}:{workUnitLimit:e.workUnitLimit},artifacts:s}}},G=async(e,t)=>{for(let t of[`sourceUnit`,`unit`,`scale`,`coordinateSystem`])if(t in e)throw m([h({code:`GEOSPEC_NATIVE_RUNTIME_FRAME_OVERRIDE`,message:`Native Runtime model loading rejects '${t}': the Runtime export intent owns the frame.`,suggestion:`Remove the frame override and let GeoSpec request canonical Z-up millimetre evidence.`,details:{key:t}})]);let n=S(e,r.format),o=n===`stp`?`step`:n,s=await L(e);await s.connect();let c=await w(s,e),l={runtime:s,format:o,...c===void 0?{}:{kernelId:c},...e.meshLinearTolerance===void 0?{}:{meshLinearTolerance:e.meshLinearTolerance},...e.meshAngularToleranceDegrees===void 0?{}:{meshAngularToleranceDegrees:e.meshAngularToleranceDegrees}},u=i(l);if(`success`in u)throw m(u.diagnostics);let d=e.region===void 0?void 0:O(e.region);if(d!==void 0){let t=C(s,o).filter(e=>c===void 0||e.kernelId===c);if(!t.some(e=>e.transcoderId===void 0&&`region`in(e.exportOptions?.schema.properties??{}))){let n=[...new Set(t.flatMap(e=>e.kernelId===void 0?[]:[e.kernelId]))];throw m([h({code:`GEOSPEC_MODEL_REGION_UNSUPPORTED`,message:`No direct ${o.toUpperCase()} export of this Runtime${n.length===0?``:` (${n.join(`, `)})`} declares a region option, so GeoSpec cannot crop '${e.file}' before admission.`,suggestion:`Load the whole model; if it exceeds a host limit, provision more resources and report the claim as not decided at this capacity. A region load needs a kernel whose GLB export crops, such as PicoVoxel, and only scopes a separate claim to that region.`,details:{file:e.file,format:o,region:d,kernelIds:n}})])}}let f={...structuredClone(u.options),...d===void 0?{}:{region:{min:[...d.min],max:[...d.max]}}},p=s.open({source:x(e),...e.parameters===void 0?{}:{parameters:e.parameters},watch:!1}),_=await(async()=>{try{return await p.export(o,{options:structuredClone(f)})}finally{p.close()}})();if(!_.success)throw m(_.issues.map(g));if(d!==void 0&&!_.issues.some(e=>{let{details:t}=e,n=typeof t==`object`&&t&&`region`in t?t.region:void 0;return typeof n==`object`&&!!n&&T(n)===T({min:[...d.min],max:[...d.max]})}))throw m([h({code:`GEOSPEC_MODEL_REGION_NOT_HONORED`,message:`The Runtime export of '${e.file}' did not confirm the requested region crop, so its bytes may be the whole model.`,suggestion:`Load the whole model, or update the kernel so its export reports the region it cropped.`,details:{file:e.file,format:o,region:d}})]);let v=[..._.files],[y,...b]=v;if(y===void 0)throw m([h({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 E=i(l);if(`success`in E)throw m(E.diagnostics);let D=await Promise.all(v.map(async({name:e,bytes:t})=>({name:e,sha256:await a(t),byteLength:t.byteLength}))),k=_.sourceRevision===void 0?void 0:structuredClone(_.sourceRevision),A=k!==void 0&&/^sha256:[0-9a-f]{64}$/u.test(k.files[k.entry]??``)&&Object.values(k.files).every(e=>e===`missing`||/^sha256:[0-9a-f]{64}$/u.test(e));return{...H({format:o,primary:y.bytes,resources:b,sourceUnit:E.sourceUnit,diagnostics:_.issues.map(g),...e.ingestOptions===void 0?{}:{ingestOptions:e.ingestOptions}},t),load:{loadId:``,status:A?`complete`:`unavailable`,format:o,parameters:e.parameters??{},exportOptions:f,ingestOptions:e.ingestOptions??{},...k===void 0?{}:{sourceRevision:k},...e.workUnitLimit===void 0?{}:{workUnitLimit:e.workUnitLimit},...d===void 0?{}:{region:d},artifacts:D}}},K=(e,t)=>{let n=u.get(r.engine)?.inputs.get(e);return n===void 0||n.owners.size===0?!1:(n.owners.add(t),E.set(t,e),l.set(e,n),!0)},q=async(e,t)=>{let n=t.status===`complete`?t.sourceRevision:void 0;if(n===void 0)return!1;let r=await L(e);if(r.snapshotSource===void 0)return!1;try{let t=await r.snapshotSource({source:{path:e.file}});return t.success&&k(n,t)}catch{return!1}},J=async(e,t)=>{let n=e.runtime??r.runtime,i=`code`in e,a=i&&Object.values(e.code).every(e=>typeof e==`string`)?e.code:void 0,o=n===void 0||i&&a===void 0||[`sourceUnit`,`unit`,`scale`,`coordinateSystem`].some(t=>t in e)?void 0:T({file:e.file,code:a,projectPath:e.projectPath??r.projectPath,format:e.format??r.format??`glb`,meshLinearTolerance:e.meshLinearTolerance,meshAngularToleranceDegrees:e.meshAngularToleranceDegrees,parameters:e.parameters,ingestOptions:e.ingestOptions,region:e.region});if(n===void 0||o===void 0)return G(e,new Set([t]));let s=M.get(n);s===void 0&&(s=new Map,M.set(n,s));let c=s.get(o);if(c!==void 0){c.owners?.add(t);let n=await c.pending;if((c.owners!==void 0||await q(e,n.load))&&K(n.subjectHash,t)){let{workUnitLimit:t,...r}=n.load;return{subjectHash:n.subjectHash,load:{...r,...e.workUnitLimit===void 0?{}:{workUnitLimit:e.workUnitLimit},reused:!0}}}}let l=new Set([t]),u=G(e,l),d={pending:u,...a===void 0?{}:{owners:l}};return s.set(o,d),u.then(void 0,()=>{s.delete(o)}),u};return Object.assign(t=>{let i={},a=F(`load`),o={...t,...`code`in t?{code:Object.fromEntries(Object.entries(t.code))}:{},...t.parameters===void 0?{}:{parameters:structuredClone(t.parameters)},...t.ingestOptions===void 0?{}:{ingestOptions:structuredClone(t.ingestOptions)},...`region`in t&&t.region!==void 0?{region:structuredClone(t.region)}:{}},s=t.format??r.format??`glb`,u=[`stepStreaming`,...t.mesh===!1&&(s===`step`||s===`stp`)?[]:[`mesh`],...`source`in t?[`meshLinearTolerance`,`meshAngularToleranceDegrees`,`region`,...s===`step`||s===`stp`?[`sourceUnit`]:[]]:[],...s===`step`||s===`stp`?[`region`]:[]].find(e=>e in t&&(e!==`region`||t[e]!==void 0));if(u!==void 0)return Promise.reject(m([h({code:`GEOSPEC_MODEL_OPTION_UNSUPPORTED`,message:`This GeoSpec host cannot honor model option '${u}'.`,suggestion:`Remove this option or configure a host that supports its declared behavior.`,details:{option:u}})]));let d=e(t.workUnitLimit,`loadModel workUnitLimit`,c);if(d!==void 0)return Promise.reject(m([h({code:`GEOSPEC_MODEL_OPTION_INVALID`,message:d,suggestion:`Pass a positive integer workUnitLimit within the stated bound, or omit it for the engine default.`,details:{option:`workUnitLimit`}})]));let f=`source`in t?void 0:D(t.region);if(f!==void 0)return Promise.reject(f);let p=`source`in t?W(o,new Set([i])):J(o,i),g=(async()=>{let e=await p,t={...e,...e.load===void 0?{}:{load:{...e.load,loadId:a}}},r=A,o=!1;return n(t,{ensureResident(){if(r!==A||!E.has(i))throw TypeError(`This subject is not admitted by the active GeoSpec host.`);U(e.subjectHash)},dispose(){if(!(o||!E.has(i))){o=!0;try{z(e.subjectHash,i),E.delete(i),[...E.values()].includes(e.subjectHash)||l.delete(e.subjectHash)}finally{o=!1}}}}),t})();return j.add(g),g},{async releaseAll(){do{let e=[...j];await Promise.allSettled(e);for(let t of e)j.delete(t)}while(j.size>0);let e=[],{carried:t}=r;if(A+=1,M.clear(),t!==void 0){for(let[n,i]of V())try{u.get(r.engine)?.inputs.has(n)?z(n,t):R(i),t.delete(n)}catch(t){e.push(t)}for(let[e,n]of l)n.handle===void 0?(n.owners.delete(t),t.delete(e)):(n.owners.add(t),t.set(e,n.handle))}for(let[t,n]of[...E].reverse())try{z(n,t),E.delete(t),[...E.values()].includes(n)||l.delete(n)}catch(t){e.push(t)}for(let t of N)try{t.shutdown?await t.shutdown():t.terminate()}catch(t){e.push(t)}if(N.clear(),P.clear(),e.length>0)throw AggregateError(e,`Native GeoSpec model cleanup failed.`)}})};export{A as createGeoSpecNativeModelLoader};

package/dist/model/region-scope.d.mts

@@ -0,0 +1,23 @@
+import "../mesh/types.mjs";
+import "./types.mjs";
+import { GeoSpecAssertion } from "../runner/types.mjs";
+//#region src/model/region-scope.d.ts
+/**
+ * The claims a region-cropped subject answers: measurements of the cropped geometry itself. Each
+ * verdict holds for the region only, and the assertion records the region it stands for.
+ *
+ * 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.
+ *
+ * @public
+ */
+declare const geoSpecRegionScopedKinds: ReadonlySet<GeoSpecAssertion['kind']>;
+/**
+ * Diagnostic code of a whole-model claim made on a region-cropped subject.
+ *
+ * @public
+ */
+declare const geoSpecRegionWholeModelClaimCode = "GEOSPEC_REGION_WHOLE_MODEL_CLAIM";
+//#endregion
+export { geoSpecRegionScopedKinds, geoSpecRegionWholeModelClaimCode };

package/dist/model/region-scope.mjs

@@ -0,0 +1 @@
+const e=new Set([`boundingBox`,`volume`,`surfaceArea`,`mass`,`centerOfMass`]),t=`GEOSPEC_REGION_WHOLE_MODEL_CLAIM`,n=(n,r)=>n===void 0||e.has(r)?void 0:{code:t,severity:`error`,message:`A '${r}' claim is about the whole model, and this subject is cropped to the region min [${n.min.join(`, `)}] max [${n.max.join(`, `)}] mm, so the claim cannot be decided on it.`,suggestion:`Keep the claim and make it on a whole-model load (loadModel without region). If the whole model exceeds a host limit, provision more resources (host admission limits or workUnitLimit) and report the claim as not decided at this capacity. A region load answers only bounding box, volume, surface area, mass and center of mass of that region.`,details:{kind:r,region:{min:[...n.min],max:[...n.max]},regionScopedKinds:[...e]}};export{e as geoSpecRegionScopedKinds,t as geoSpecRegionWholeModelClaimCode,n as regionScopeRefusal};

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";import{regionScopeRefusal as i}from"./region-scope.mjs";const a=(a,o)=>{let s=e(a),c=o?.workUnitLimit??s.load?.workUnitLimit,l=s.client.expectGeo(s.identity,c===void 0?void 0:{workUnitLimit:c}),u=o=>t({subject:a,polarity:o?`negative`:`positive`,invoke:t=>{e(a);let c=s.load?.region,u=c===void 0?void 0:{min:[...c.min],max:[...c.max]},d=u===void 0?{}:{region:u},f=i(c,t.kind);if(f!==void 0)return{kind:t.kind,subject:s.identity,...s.load===void 0?{}:{loadId:s.load.loadId},...d,expected:t.expected,passed:!1,diagnostics:[f]};let p=o?l.not:l,m=Reflect.apply(p[t.matcher],p,t.arguments),h=m.diagnostics.map(e=>n(r.parse(e)));return{kind:t.kind,subject:s.identity,...s.load===void 0?{}:{loadId:s.load.loadId},...d,expected:t.expected,passed:m.status===`passed`,diagnostics:h,report:m}}});return Object.assign(u(!1),{not:u(!0)})};export{a 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,254 @@
+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. A client with
+ * `snapshotSource` lets one run reuse an identical file load after confirming
+ * that the source closure it exported is unchanged.
+ *
+ * @public
+ */
+type 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<{
+      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>;
+};
+/**
+ * Axis-aligned crop box in canonical Z-up millimetres; every `min` axis is below its `max` axis.
+ *
+ * @public
+ */
+type GeoSpecLoadRegion = {
+  readonly min: readonly [number, number, number];
+  readonly max: readonly [number, number, number];
+};
+/**
+ * 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;
+  /**
+   * 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;
+};
+/**
+ * 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;
+  /**
+   * 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;
+};
+/**
+ * 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;
+  /**
+   * 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;
+};
+/**
+ * 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, GeoSpecLoadRegion, GeoSpecModelFormat, GeoSpecModelLoader, GeoSpecRuntimeClient, GeoSpecRuntimeClientFactory, GeoSpecRuntimeSourceAdapter, LoadModelCodeOptions, LoadModelFileOptions, LoadModelOptions, LoadModelSourceOptions, ManagedGeoSpecModelLoader, MeshBufferSource, MeshSource };

package/dist/runner/collector.d.mts

@@ -0,0 +1,64 @@
+import { GeometryDiagnostic } from "../mesh/types.mjs";
+import { GeoSpecExpectOptions, GeoSpecMatcher, GeoSpecTestCase, GeoSpecTestEvent } 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, options?: GeoSpecExpectOptions): 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;
+  /** Observes each selected test as it starts and settles, for host progress reporting. */
+  onTestEvent?: (event: GeoSpecTestEvent) => void;
+};
+/**
+ * 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{assertGeoSpecAuthoredWorkUnitLimit as e}from"../engine/client.mjs";import{resolveGeoSpecSubject as t}from"../model/subject.mjs";import{GeoSpecAssertionError as n,createGeoSpecAssertionClient as r,createGeoSpecMatcherMethods as i}from"../assertion-client/client.mjs";import{diagnosticForTransport as a,geometryDiagnosticSchema as o}from"../model/errors.mjs";import{matchesGeoSpecTestName as s}from"./filter.mjs";import{geoSpecTimeoutCode as c}from"./timeout-codes.mjs";import{regionScopeRefusal as l}from"../model/region-scope.mjs";const u=`__GEOSPEC_COLLECTOR__`,d=globalThis,f=e=>typeof e==`object`&&!!e&&`then`in e&&typeof e.then==`function`;var p=class extends Error{diagnostics;constructor(e){super(e.map(e=>e.message).join(`
+`)||`GeoSpec assertion failed.`),this.name=`GeoSpecAssertionError`,this.diagnostics=Object.freeze([...e])}},m=class extends Error{testTimeout;constructor(e){super(`GeoSpec test timed out after ${e}ms.`),this.name=`GeoSpecTestTimeoutError`,this.testTimeout=e}};const h=e=>{if(e instanceof p)return[...e.diagnostics];if(e instanceof m)return[{code:c.test,severity:`error`,message:`${e.message} The test still ran to completion before the run moved on; this is a wall-clock timeout, not a geometry verdict.`,suggestion:`Keep the assertion and the model as designed. Raise testTimeout (CLI --test-timeout) so the requirement can finish; if this host cannot give it the time, report it as not decided at this capacity.`,details:{testTimeout:e.testTimeout}}];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=>a(g(e)))}catch{}}let t=typeof e==`object`&&e&&typeof Reflect.get(e,`message`)==`string`?String(Reflect.get(e,`message`)):String(e),{details:n}=a({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}]},g=e=>o.parse(e),_=(e,t)=>{if(e.passed=t.length===0,e.diagnostics=t,t.length>0)throw new p(t);return e},v=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(t))},t)})])}finally{n!==void 0&&clearTimeout(n)}},y=(e,t)=>{for(let n of e)n.status===`rejected`&&t(n.reason)},b=()=>{let e=d[u];if(!x(e))throw Error(`GeoSpec collector is not active. Run the module through runGeoSpecModule().`);return e},x=e=>typeof e==`object`&&!!e&&`describe`in e&&`it`in e&&`expectGeo`in e&&`tests`in e,S=e=>typeof e==`object`&&!!e&&`suite`in e&&`name`in e&&`assertions`in e;function C(o){let c=r(o.nativeAssertions),u=[],d=[],m=[],b=[],x=new WeakSet,C,w=!1,T=(e,t)=>{try{o.onTestEvent?.({type:e,test:t})}catch{}},E=(e,t)=>{m.push((async()=>{try{await e}catch(e){t.onError(e)}finally{t.onFinally()}})())},D=e=>{d.push({ordinal:d.length,suite:[...u],name:e,assertions:[],status:`skipped`,diagnostics:[]})},O=(e,r)=>{if(!S(C))throw Error(`expectGeo() must be called inside it().`);let i={kind:e.kind,subject:null,expected:e.expected};C.assertions.push(i);let s=performance.now();try{let s=t(e.subject,o.nativeAssertions.engine);i.subject=s.identity,s.load!==void 0&&(i.loadId=s.load.loadId);let u=s.load?.region;u!==void 0&&(i.region={min:[...u.min],max:[...u.max]});let d=l(u,e.kind);if(d!==void 0)return _(i,[d]);let f=r?.workUnitLimit??s.load?.workUnitLimit,p=c.expectGeo(s.identity,f===void 0?void 0:{workUnitLimit:f}),m=(e.polarity===`negative`?p.not:p)[e.matcher],h;try{h=m(...e.arguments)}catch(e){if(!(e instanceof n))throw e;h=e.report}if(i.report=h,h.status===`passed`)return _(i,[]);let v=h.diagnostics.map(e=>a(g(e)));return _(i,v.length>0?v:[{code:`GEOSPEC_NATIVE_ASSERTION_FAILED`,severity:`error`,message:`Native claim '${h.claimId}' ended with status '${h.status}'.`,details:{claimId:h.claimId,status:h.status}}])}catch(e){throw e instanceof p&&i.report!==void 0&&x.add(e),i.passed=!1,i.diagnostics??=h(e),e}finally{i.durationMs=performance.now()-s}};return{describe(e,t){u.push(e);try{let n=t();if(f(n)){let t=[...u];E(n,{onError(n){d.push({ordinal:d.length,suite:t,name:e,assertions:[],status:`failed`,diagnostics:h(n)})},onFinally(){u.pop()}});return}}catch(t){d.push({ordinal:d.length,suite:[...u],name:e,assertions:[],status:`failed`,diagnostics:h(t)})}u.pop()},describeSkip(e){D(e)},it(e,t){let n={ordinal:d.length,suite:[...u],name:e,assertions:[],status:`not-run`,diagnostics:[]};d.push(n),b.push({test:n,function_:t})},itSkip(e){D(e)},expectGeo(t,n){e(n?.workUnitLimit,`expectGeo workUnitLimit`,o.nativeAssertions.maximumWorkUnitLimit);let r=e=>O(e,n);return Object.assign(i({invoke:r,polarity:`positive`,subject:t}),{not:i({invoke:r,polarity:`negative`,subject:t})})},async waitForCompletion(e,t){if(w)return;w=!0;let n=Promise.allSettled(m);try{await v(n,e)}catch(e){throw await n,e}for(let n of b){if(!s(n.test,t))continue;let r=C;C=n.test,n.test.status=`passed`,T(`test-start`,n.test);let i=performance.now(),a=[],o=e=>{a.some(t=>Object.is(t,e))||a.push(e)};try{let t;try{t=Promise.resolve(n.function_()),await v(t,e)}catch(e){o(e)}if(t!==void 0&&y(await Promise.allSettled([t]),o),a.length>0||n.test.assertions.some(e=>e.passed===!1)){n.test.status=`failed`;for(let e of a)n.test.diagnostics.push(...h(e));let{assertions:e}=n.test;if(!(a.some(e=>!(e instanceof p)||!x.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{C=r,n.test.durationMs=performance.now()-i,T(`test-complete`,n.test)}}},tests:d}}const w=()=>{Reflect.deleteProperty(d,u)},T=e=>{d[u]=e};export{p as GeoSpecAssertionError,w as clearCollectorGlobals,u as collectorGlobalKey,C as createCollector,b as getCollector,T as installCollector};