geospec 0.1.0-beta.9 → 0.4.1-next.331

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

@@ -1,333 +1,6 @@
 # geospec — Types (2)
 
-57 top-level symbols. Signatures are verbatim typescript.
-
-// Inline code-CAD model load options
-LoadModelCodeOptions: {
-    /** Source files keyed by project-relative path. */
-    code: Code;
-    /** Entry path to render from {@link code}. */
-    file: keyof Code & string;
-    /** Not accepted: inline code has no project folder to resolve in, and a load naming one is refused. */
-    rootDir?: never;
-    /** Geometry format to export. Defaults to `glb`. */
-    format?: GeoSpecModelFormat;
-    /** Explicit parameters passed to the exporter. */
-    parameters?: Record<string, unknown>;
-    /** Absolute project root passed to the exporter. */
-    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 exporter crops the model to before export, so a large mesh model
-     * can be checked region by region. Only an exporter that declares `region` honours it; any other
-     * exporter, or a crop the exporter cannot make, refuses with a typed diagnostic instead of loading
-     * the whole model. The cropped subject is a different subject: its load evidence records `region`,
-     * so a claim on it never stands for the whole model.
-     */
-    region?: GeoSpecLoadRegion;
-}
-
-  // Source files keyed by project-relative path
-  code: Code
-
-  // Entry path to render from {@link code }
-  file: keyof Code & string
-
-  // Not accepted
-  rootDir?: never
-
-  // Geometry format to export
-  format?: GeoSpecModelFormat
-
-  // Explicit parameters passed to the exporter
-  parameters?: Record<string, unknown>
-
-  // Absolute project root passed to the exporter
-  projectPath?: string
-
-  // STEP reader strategy used for STEP exports
-  stepStreaming?: StepStreamingMode
-
-  // Whether STEP loading should also produce mesh evidence
-  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
-  workUnitLimit?: number
-
-  // Axis-aligned millimetre box the exporter crops the model to before export, so a large mesh model can be checked region by region
-  region?: GeoSpecLoadRegion
-
-// Filesystem-backed model load options
-LoadModelFileOptions: {
-    /**
-     * Model file to render, as a path from the project root: the same root every tool's `targetFile` resolves
-     * against, which the result names as `projectRoot` where the host reports it, as `tau mcp` does.
-     */
-    file: string;
-    /**
-     * Project-relative folder `file` resolves in, for a suite that loads from somewhere other than the project root:
-     * `loadModel({ file: 'main.ts', rootDir: 'parts/gear' })` loads `parts/gear/main.ts`. Recorded in the load
-     * evidence.
-     */
-    rootDir?: string;
-    /** Absolute project root passed to the exporter. */
-    projectPath?: string;
-    /** Geometry format to export. Defaults to `glb`. */
-    format?: GeoSpecModelFormat;
-    /** Explicit parameters passed to the exporter. */
-    parameters?: Record<string, unknown>;
-    /** 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 exporter crops the model to before export, so a large mesh model
-     * can be checked region by region. Only an exporter that declares `region` honours it; any other
-     * exporter, or a crop the exporter cannot make, refuses with a typed diagnostic instead of loading
-     * the whole model. The cropped subject is a different subject: its load evidence records `region`,
-     * so a claim on it never stands for the whole model.
-     */
-    region?: GeoSpecLoadRegion;
-}
-
-  // Model file to render, as a path from the project root
-  file: string
-
-  // Project-relative folder `file` resolves in, for a suite that loads from somewhere other than the project root
-  rootDir?: string
-
-  // Absolute project root passed to the exporter
-  projectPath?: string
-
-  // Geometry format to export
-  format?: GeoSpecModelFormat
-
-  // Explicit parameters passed to the exporter
-  parameters?: Record<string, unknown>
-
-  // STEP reader strategy used for STEP exports
-  stepStreaming?: StepStreamingMode
-
-  // Whether STEP loading should also produce mesh evidence
-  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
-  workUnitLimit?: number
-
-  // Axis-aligned millimetre box the exporter crops the model to before export, so a large mesh model can be checked region by region
-  region?: GeoSpecLoadRegion
-
-// Options accepted by {@link import ('./load-model.js').loadModel}
-LoadModelOptions: LoadModelSourceOptions | LoadModelCodeOptions<Code> | LoadModelFileOptions
-
-  // Project-relative folder `file` resolves in, for a suite that loads from somewhere other than the project root
-  rootDir?: string
-
-  // Geometry format to export
-  format?: GeoSpecModelFormat
-
-  // Explicit parameters passed to the exporter
-  parameters?: Record<string, unknown>
-
-  // STEP reader strategy used for STEP exports
-  stepStreaming?: StepStreamingMode
-
-  // Whether STEP loading should also produce mesh evidence
-  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
-  workUnitLimit?: number
-
-// Direct geometry-source model load options
-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;
-    }>;
-    /**
-     * Project-relative folder a path `source` and each resource path resolve in. Omitted, they resolve against the
-     * project root. Recorded in the load evidence.
-     */
-    rootDir?: string;
-    /** 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;
-}
-
-  // 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;
-      }>
-
-  // Project-relative folder a path `source` and each resource path resolve in
-  rootDir?: string
-
-  // Source geometry format
-  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
-  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
-  workUnitLimit?: number
-
-// Options for {@link commandExporter}
-CommandExporterOptions: {
-    readonly id: string;
-    /** File extensions without the dot, or `'*'`. */
-    readonly extensions: readonly string[];
-    /** Executable and leading arguments, such as `['python', 'export.py']`. */
-    readonly command: readonly string[];
-    /** What the command can do. Protocol 1 carries no inline sources, so `inlineSources` must not be set. */
-    readonly capabilities: GeoSpecExporterCapabilities;
-    /** Working directory of the command; defaults to the request's project root. */
-    readonly cwd?: string;
-    /** Extra environment variables, merged over this process's. */
-    readonly env?: Readonly<Record<string, string>>;
-    /** Positive milliseconds one export may run before the command is killed and the export fails. */
-    readonly exportTimeout?: number;
-}
-
-  readonly id: string
-
-  // File extensions without the dot, or `'*'`
-  readonly extensions: readonly string[]
-
-  // Executable and leading arguments, such as `['python', 'export.py']`
-  readonly command: readonly string[]
-
-  // What the command can do
-  readonly capabilities: GeoSpecExporterCapabilities
-
-  // Working directory of the command
-  readonly cwd?: string
-
-  // Extra environment variables, merged over this process's
-  readonly env?: Readonly<Record<string, string>>
-
-  // Positive milliseconds one export may run before the command is killed and the export fails
-  readonly exportTimeout?: number
-
-// Collects suites, tests, assertions, and async completion state for one GeoSpec module execution
-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>;
-}
-
-  tests: GeoSpecTestCase[]
-
-  // GeoSpecCollector.describe (method)
-  describe(name: string, function_: GeoSpecTestFunction): void;
-
-  // GeoSpecCollector.describeSkip (method)
-  describeSkip(name: string, _function?: GeoSpecTestFunction): void;
-
-  // GeoSpecCollector.it (method)
-  it(name: string, function_: GeoSpecTestFunction): void;
-
-  // GeoSpecCollector.itSkip (method)
-  itSkip(name: string, _function?: GeoSpecTestFunction): void;
-
-  // GeoSpecCollector.expectGeo (method)
-  expectGeo(subject: unknown, options?: GeoSpecExpectOptions): GeoSpecMatcher;
-
-  // GeoSpecCollector.waitForCompletion (method)
-  waitForCompletion(testTimeout?: number, testNamePattern?: GeoSpecTestNamePattern): Promise<void>;
+72 top-level symbols. Signatures are verbatim typescript.
 
 // Per-module collector configuration
 GeoSpecCollectorOptions: {
@@ -499,7 +172,7 @@ GeoSpecTestCase: {
     status: GeoSpecTestStatus;
     /** Structured diagnostics emitted by test execution. */
     diagnostics: GeometryDiagnostic[];
-    /** Wall-clock cost of the test body plus its pending assertions, in milliseconds (R1). */
+    /** Wall-clock cost of the test body plus its pending assertions, in milliseconds. */
     durationMs?: number;
 }
 
@@ -521,7 +194,7 @@ GeoSpecTestCase: {
   // Structured diagnostics emitted by test execution
   diagnostics: GeometryDiagnostic[]
 
-  // Wall-clock cost of the test body plus its pending assertions, in milliseconds (R1)
+  // Wall-clock cost of the test body plus its pending assertions, in milliseconds
   durationMs?: number
 
 // A selected test starting or settling inside a module run
@@ -561,10 +234,15 @@ RunGeoSpecModuleOptions: {
     }>;
     /** Additional in-memory modules made available to the VM. */
     builtinModules?: Record<string, BuiltinModule>;
+    /**
+     * Module VM factory; defaults to {@link import('../vm/plain-module-vm.js').createPlainModuleVm}, which resolves
+     * project files and builtins only. Inject one to resolve npm packages; Tau injects `createEsbuildModuleVm`.
+     */
+    createModuleVm?: CreateModuleVm;
     /** Successful bundle cache owned by a serial runner worker. @internal */
     bundleCache?: GeoSpecModuleBundleCache;
     /**
-     * List-only collection pass (R3 shard splitting): execute the module to
+     * List-only collection pass (shard splitting): execute the module to
      * REGISTER tests, skip every body, and return all registered tests as
      * `skipped` in registration order. Used by the pool to split heavy files
      * into per-test shards.
@@ -598,12 +276,220 @@ RunGeoSpecModuleOptions: {
   // Additional in-memory modules made available to the VM
   builtinModules?: Record<string, BuiltinModule>
 
+  // Module VM factory
+  createModuleVm?: CreateModuleVm
+
   // Successful bundle cache owned by a serial runner worker
   bundleCache?: GeoSpecModuleBundleCache
 
-  // List-only collection pass (R3 shard splitting)
+  // List-only collection pass (shard splitting)
   collectOnly?: boolean
 
+// A pre-bundled module served from memory under its import specifier
+BuiltinModule: {
+    /** ESM source of the module. */
+    code: string;
+    /** Version reported for the module. */
+    version: string;
+    /** Script global that bundles bind to this module; bound only when `registryExpression` is set. */
+    globalName?: string;
+    /** The npm package this module stands for, as a project declares it in `package.json`. */
+    package?: {
+        readonly name: string;
+        readonly spec: string;
+    };
+    /** JavaScript expression evaluating to the module's exports, which a bundle binds to `globalName`. */
+    registryExpression?: string;
+}
+
+  // ESM source of the module
+  code: string
+
+  // Version reported for the module
+  version: string
+
+  // Script global that bundles bind to this module
+  globalName?: string
+
+  // The npm package this module stands for, as a project declares it in `package.json`
+  package?: {
+          readonly name: string;
+          readonly spec: string;
+      }
+
+  // JavaScript expression evaluating to the module's exports, which a bundle binds to `globalName`
+  registryExpression?: string
+
+// Outcome of bundling an entry point
+BundleResult: {
+    code: string;
+    sourceMap?: string;
+    issues: VmIssue[];
+    success: boolean;
+    dependencies: string[];
+    unresolvedPaths: string[];
+}
+
+  code: string
+
+  sourceMap?: string
+
+  issues: VmIssue[]
+
+  success: boolean
+
+  dependencies: string[]
+
+  unresolvedPaths: string[]
+
+// Create a module VM
+CreateModuleVm: (options: ModuleVmOptions) => Promise<ModuleVm>
+
+// A module a Node pool worker imports by URL for its module VM
+GeoSpecModuleVmModule: {
+    default: CreateModuleVm;
+}
+
+  default: CreateModuleVm
+
+// The ESM module VM GeoSpec bundles and executes specs and configs with
+ModuleVm: {
+    /** Detect bare specifiers and project dependencies without fetching anything. */
+    detectImports(entryPath: string, signal?: AbortSignal): Promise<{
+        detectedModules: string[];
+        dependencies: string[];
+    }>;
+    /** Bundle an ESM entry point and its transitive dependency graph. */
+    bundle(entryPath: string, signal?: AbortSignal): Promise<BundleResult>;
+    /** Execute bundled ESM code in the current JavaScript environment. */
+    execute<T = unknown>(code: string, signal?: AbortSignal): Promise<VmExecuteResult<T>>;
+    /** Register an in-memory builtin module. */
+    registerModule(name: string, module: BuiltinModule): void;
+    /** Release VM-owned resources. */
+    dispose(): void;
+}
+
+  // Detect bare specifiers and project dependencies without fetching anything
+  // ModuleVm.detectImports (method)
+  detectImports(entryPath: string, signal?: AbortSignal): Promise<{
+          detectedModules: string[];
+          dependencies: string[];
+      }>;
+
+  // Bundle an ESM entry point and its transitive dependency graph
+  // ModuleVm.bundle (method)
+  bundle(entryPath: string, signal?: AbortSignal): Promise<BundleResult>;
+
+  // Execute bundled ESM code in the current JavaScript environment
+  // ModuleVm.execute (method)
+  execute<T = unknown>(code: string, signal?: AbortSignal): Promise<VmExecuteResult<T>>;
+
+  // Register an in-memory builtin module
+  // ModuleVm.registerModule (method)
+  registerModule(name: string, module: BuiltinModule): void;
+
+  // Release VM-owned resources
+  // ModuleVm.dispose (method)
+  dispose(): void;
+
+// Options GeoSpec passes when it creates a module VM
+ModuleVmOptions: {
+    /** Filesystem the VM reads project files from. */
+    filesystem: VmFileSystem;
+}
+
+  // Filesystem the VM reads project files from
+  filesystem: VmFileSystem
+
+// Result of executing bundled ESM code
+VmExecuteResult: {
+    success: true;
+    value: T;
+    entryUrl?: string;
+} | {
+    success: false;
+    issues: VmIssue[];
+}
+
+  success: true
+
+// Minimal filesystem contract required by the VM bundler
+VmFileSystem: {
+    /** Return true when a path exists. */
+    exists(path: string): Promise<boolean>;
+    /** Read a file as binary bytes. */
+    readFile(path: string): Promise<Uint8Array<ArrayBuffer>>;
+    /** Read a file as UTF-8 text. */
+    readFile(path: string, encoding: 'utf8'): Promise<string>;
+    /** Write a UTF-8 text file. */
+    writeFile(path: string, content: string): Promise<void>;
+    /** Ensure a directory exists, creating parents as needed. */
+    ensureDir(path: string): Promise<void>;
+}
+
+  // Return true when a path exists
+  // VmFileSystem.exists (method)
+  exists(path: string): Promise<boolean>;
+
+  // Read a file as binary bytes
+  // VmFileSystem.readFile (method)
+  readFile(path: string): Promise<Uint8Array<ArrayBuffer>>;
+  readFile(path: string, encoding: 'utf8'): Promise<string>;
+
+  // Write a UTF-8 text file
+  // VmFileSystem.writeFile (method)
+  writeFile(path: string, content: string): Promise<void>;
+
+  // Ensure a directory exists, creating parents as needed
+  // VmFileSystem.ensureDir (method)
+  ensureDir(path: string): Promise<void>;
+
+// A diagnostic emitted while bundling or executing a VM module
+VmIssue: {
+    /** Human-readable diagnostic message. */
+    message: string;
+    /** Stable machine-readable code. */
+    code: string;
+    /** Diagnostic category. */
+    type: string;
+    /** Diagnostic severity. */
+    severity: 'error' | 'warning' | 'info';
+    /** Optional source location. */
+    location?: {
+        fileName?: string;
+        startLineNumber?: number;
+        startColumn?: number;
+        endLineNumber?: number;
+        endColumn?: number;
+    };
+    /** Optional original error object or metadata. */
+    details?: unknown;
+}
+
+  // Human-readable diagnostic message
+  message: string
+
+  // Stable machine-readable code
+  code: string
+
+  // Diagnostic category
+  type: string
+
+  // Diagnostic severity
+  severity: 'error' | 'warning' | 'info'
+
+  // Optional source location
+  location?: {
+          fileName?: string;
+          startLineNumber?: number;
+          startColumn?: number;
+          endLineNumber?: number;
+          endColumn?: number;
+      }
+
+  // Optional original error object or metadata
+  details?: unknown
+
 // Native assertion options whose engine can also admit and release subjects
 GeoSpecNativeRunnerAssertions: Omit<GeoSpecAssertionClientOptions, 'engine'> & {
     readonly engine: GeoSpecNativeModelEngine;
@@ -639,6 +525,9 @@ GeoSpecNativeRunnerOptions: Omit<GeoSpecRunnerOptions, 'nativeAssertions' | 'nat
   // Additional in-memory modules made available to the VM
   builtinModules?: RunGeoSpecModuleOptions['builtinModules']
 
+  // Module VM factory for every file
+  createModuleVm?: RunGeoSpecModuleOptions['createModuleVm']
+
   // Actual protocol-3 engine used by authored assertions
   readonly nativeAssertions: GeoSpecNativeRunnerAssertions
 
@@ -749,7 +638,7 @@ GeoSpecNativeModelEngine: GeoSpecNativeEngine & {
   releaseSubject(request: Uint8Array<ArrayBuffer>): Uint8Array<ArrayBuffer>;
 
 // Model loader injected into native VM runs
-// Remarks: 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. Exported 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 the exporter's `revision` 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.
+// Remarks: 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. Exported loads are coalesced per release scope (one run): a load whose options all equal an earlier successful load's (file, code, project path, parameters, format, tolerances, region, ingest) reuses that admission. A file load is reused only while the exporter's `revision` 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.
 GeoSpecNativeModelLoader: <Code extends Record<string, string> = Record<string, string>>(options: GeoSpecNativeLoadModelOptions<Code>) => Promise<GeoSpecNativeModelSubject>
 
 // Subject identity returned by native STEP/GLB admission
@@ -839,6 +728,11 @@ GeoSpecNodePoolOptions: {
      * `GeoSpecExporterModule`). A host that composes its own exporters, such as `tau test`, passes them here.
      */
     exporterModules?: readonly string[];
+    /**
+     * URL of a module each worker imports whose default export creates its module VM (see `GeoSpecModuleVmModule`);
+     * absent for GeoSpec's plain VM. A host that resolves npm packages in specs, such as `tau test`, passes it here.
+     */
+    moduleVmModule?: string;
     /** Number of outer worker isolates; defaults to one. */
     workers?: number;
     /**
@@ -850,6 +744,11 @@ GeoSpecNodePoolOptions: {
     budget?: number;
     /** Non-verdict shard watchdog in milliseconds. */
     shardTimeout?: number;
+    /**
+     * Spec sources each worker serves from memory, keyed by project-rooted path, in place of the file on disk. A path
+     * here is never read from or written to the project; `geospec check` runs its bundled spec this way.
+     */
+    sources?: Readonly<Record<string, string>>;
 }
 
   // Absolute project root
@@ -861,6 +760,9 @@ GeoSpecNodePoolOptions: {
   // URLs of modules each worker imports whose default export creates exporters that precede the config's (see `GeoSpecExporterModule`)
   exporterModules?: readonly string[]
 
+  // URL of a module each worker imports whose default export creates its module VM (see `GeoSpecModuleVmModule`)
+  moduleVmModule?: string
+
   // Number of outer worker isolates
   workers?: number
 
@@ -870,6 +772,9 @@ GeoSpecNodePoolOptions: {
   // Non-verdict shard watchdog in milliseconds
   shardTimeout?: number
 
+  // Spec sources each worker serves from memory, keyed by project-rooted path, in place of the file on disk
+  sources?: Readonly<Record<string, string>>
+
 // The slice of `node:worker_threads`' `Worker` the pool drives
 // Remarks: Declared structurally so the adapter can be exercised against a stub as well as against a real thread (D-8: vitest cannot host a TypeScript worker).
 NodeWorkerLike: {
@@ -910,7 +815,7 @@ GeoSpecPoolHostMessage: {
     testNamePattern?: string;
     testTimeout?: number;
 } | {
-    /** List-only collection pass: register tests, run no bodies (R3 splitting). */
+    /** List-only collection pass: register tests, run no bodies (shard splitting). */
     type: 'list-tests';
     shardId: number;
     file: string;
@@ -927,7 +832,7 @@ GeoSpecPoolShard: {
     id: number;
     /** GeoSpec file this shard executes. */
     file: string;
-    /** Exact-test pattern for split shards (R3: `(file, testNamePattern)` work units). */
+    /** Exact-test pattern for split shards (`(file, testNamePattern)` work units). */
     testNamePattern?: string;
 }
 
@@ -937,7 +842,7 @@ GeoSpecPoolShard: {
   // GeoSpec file this shard executes
   file: string
 
-  // Exact-test pattern for split shards (R3
+  // Exact-test pattern for split shards (`(file, testNamePattern)` work units)
   testNamePattern?: string
 
 GeoSpecPoolWorkerHandle: {
@@ -947,7 +852,7 @@ GeoSpecPoolWorkerHandle: {
         unexpected: boolean;
         message?: string;
     }) => void): void;
-    /** Hard-stop the worker thread (R11 watchdog primitive). */
+    /** Hard-stop the worker thread (the watchdog primitive). */
     terminate(): Promise<void> | void;
 }
 
@@ -963,7 +868,7 @@ GeoSpecPoolWorkerHandle: {
           message?: string;
       }) => void): void;
 
-  // Hard-stop the worker thread (R11 watchdog primitive)
+  // Hard-stop the worker thread (the watchdog primitive)
   // GeoSpecPoolWorkerHandle.terminate (method)
   terminate(): Promise<void> | void;
 
@@ -1080,11 +985,11 @@ GeoSpecRunnerFileResult: {
     file: string;
     /** Low-level module execution result for this file. */
     result: GeoSpecRunResult;
-    /** Wall-clock cost of executing this file, in milliseconds (R1). */
+    /** Wall-clock cost of executing this file, in milliseconds. */
     durationMs?: number;
-    /** First deterministic model-load cache key observed in this file (R9 affinity telemetry). */
+    /** First deterministic model-load cache key observed in this file (affinity telemetry). */
     primaryLoadKey?: string;
-    /** Executing worker's isolate-resident memory at file completion, in bytes (R15 memory-class telemetry). */
+    /** Executing worker's isolate-resident memory at file completion, in bytes (memory-class telemetry). */
     workerMemoryBytes?: number;
 }
 
@@ -1094,13 +999,13 @@ GeoSpecRunnerFileResult: {
   // Low-level module execution result for this file
   result: GeoSpecRunResult
 
-  // Wall-clock cost of executing this file, in milliseconds (R1)
+  // Wall-clock cost of executing this file, in milliseconds
   durationMs?: number
 
-  // First deterministic model-load cache key observed in this file (R9 affinity telemetry)
+  // First deterministic model-load cache key observed in this file (affinity telemetry)
   primaryLoadKey?: string
 
-  // Executing worker's isolate-resident memory at file completion, in bytes (R15 memory-class telemetry)
+  // Executing worker's isolate-resident memory at file completion, in bytes (memory-class telemetry)
   workerMemoryBytes?: number
 
 // Shared options for GeoSpec runner factories
@@ -1113,6 +1018,8 @@ GeoSpecRunnerOptions: {
     nativeModelLoader?: ManagedGeoSpecNativeModelLoader;
     /** Additional in-memory modules made available to the VM. */
     builtinModules?: RunGeoSpecModuleOptions['builtinModules'];
+    /** Module VM factory for every file; defaults to GeoSpec's plain VM (see `RunGeoSpecModuleOptions`). */
+    createModuleVm?: RunGeoSpecModuleOptions['createModuleVm'];
 }
 
   // Filesystem containing the project and test modules
@@ -1127,6 +1034,9 @@ GeoSpecRunnerOptions: {
   // Additional in-memory modules made available to the VM
   builtinModules?: RunGeoSpecModuleOptions['builtinModules']
 
+  // Module VM factory for every file
+  createModuleVm?: RunGeoSpecModuleOptions['createModuleVm']
+
 // Aggregate result returned by GeoSpec worker-style runners
 GeoSpecRunnerResult: {
     /** True when no files or tests failed and at least one test was selected. */
@@ -1141,7 +1051,7 @@ GeoSpecRunnerResult: {
     files: GeoSpecRunnerFileResult[];
     /** Run-level issues such as aborts or empty filter selections. */
     issues?: VmIssue[];
-    /** Wall-clock cost of the whole run, in milliseconds (R1). */
+    /** Wall-clock cost of the whole run, in milliseconds. */
     durationMs?: number;
     /** Complete requested-file accounting; discovery may remain unknown in unstarted or broken modules. */
     accounting?: GeoSpecRunnerAccounting;
@@ -1167,7 +1077,7 @@ GeoSpecRunnerResult: {
   // Run-level issues such as aborts or empty filter selections
   issues?: VmIssue[]
 
-  // Wall-clock cost of the whole run, in milliseconds (R1)
+  // Wall-clock cost of the whole run, in milliseconds
   durationMs?: number
 
   // Complete requested-file accounting
@@ -1191,7 +1101,7 @@ GeoSpecRunnerRunOptions: {
      */
     workUnitLimit?: number;
     /**
-     * Stop after the first failing file (R1). Interactive fail-fast only —
+     * Stop after the first failing file. Interactive fail-fast only —
      * never the default for reward runs, which want the complete red set.
      */
     bail?: boolean;
@@ -1209,7 +1119,7 @@ GeoSpecRunnerRunOptions: {
   // Engine work-unit budget for this run's claims, replacing the runner's `nativeAssertions.workUnitLimit`
   workUnitLimit?: number
 
-  // Stop after the first failing file (R1)
+  // Stop after the first failing file
   bail?: boolean
 
 // Everything the pool needs that differs between Node and the browser
@@ -1224,7 +1134,7 @@ GeoSpecPoolOptions: {
     workers: number;
     /** Optional scheduling telemetry. Absent = declared order, no memory class. */
     timings?: ShardTimings;
-    /** Per-shard non-verdict watchdog, milliseconds (R11). */
+    /** Per-shard non-verdict watchdog, milliseconds. */
     shardTimeout?: number;
     /** Split files whose recorded duration exceeds this. Milliseconds. */
     splitThreshold?: number;
@@ -1245,7 +1155,7 @@ GeoSpecPoolOptions: {
   // Optional scheduling telemetry
   timings?: ShardTimings
 
-  // Per-shard non-verdict watchdog, milliseconds (R11)
+  // Per-shard non-verdict watchdog, milliseconds
   shardTimeout?: number
 
   // Split files whose recorded duration exceeds this
@@ -1303,11 +1213,13 @@ GeoSpecPoolWorkerHostOptions: {
     nativeModelLoader: ManagedGeoSpecNativeModelLoader;
     /** Additional in-memory modules made available to the VM. */
     builtinModules?: GeoSpecRunnerOptions['builtinModules'];
+    /** Module VM factory for every shard; defaults to GeoSpec's plain VM. */
+    createModuleVm?: GeoSpecRunnerOptions['createModuleVm'];
     /** Post a message to the pool host. */
     postMessage: (message: GeoSpecPoolWorkerMessage) => void;
     /** Subscribe to pool-host messages. */
     onHostMessage: (listener: (message: GeoSpecPoolHostMessage) => void) => void;
-    /** Sample this worker's resident memory in bytes (R15 telemetry); optional. */
+    /** Sample this worker's resident memory in bytes, as telemetry; optional. */
     measureMemoryBytes?: () => number | undefined;
     /** Release platform resources on shutdown, after the native subjects are released. */
     onShutdown?: () => Promise<void> | void;
@@ -1325,13 +1237,16 @@ GeoSpecPoolWorkerHostOptions: {
   // Additional in-memory modules made available to the VM
   builtinModules?: GeoSpecRunnerOptions['builtinModules']
 
+  // Module VM factory for every shard
+  createModuleVm?: GeoSpecRunnerOptions['createModuleVm']
+
   // Post a message to the pool host
   postMessage: (message: GeoSpecPoolWorkerMessage) => void
 
   // Subscribe to pool-host messages
   onHostMessage: (listener: (message: GeoSpecPoolHostMessage) => void) => void
 
-  // Sample this worker's resident memory in bytes (R15 telemetry)
+  // Sample this worker's resident memory in bytes, as telemetry
   measureMemoryBytes?: () => number | undefined
 
   // Release platform resources on shutdown, after the native subjects are released
@@ -1419,3 +1334,216 @@ GeoSpecAuthoringInvocation: {
 GeoSpecMatcherMethods: {
     [Name in GeoSpecMatcherName]: (...arguments_: Parameters<GeoSpecMatcher[Name]>) => Result;
 }
+
+// One positive-only ancillary query
+// Remarks: An explicit claimId leaves the automatic sequence unchanged. Queries return full reports without assertion errors. A query asserts nothing, so it never fails: one whose evidence is missing or cannot decide returns a refused report whose diagnostic names the reason, such as `GEOSPEC_UNSUPPORTED_EVIDENCE`.
+GeoSpecQueryOptions: {
+    readonly capability: GeoSpecQueryCapability;
+    readonly claimId?: string;
+    readonly payload?: unknown;
+    readonly subject: GeoSpecNativeSubject;
+}
+
+  readonly capability: GeoSpecQueryCapability
+
+  readonly claimId?: string
+
+  readonly payload?: unknown
+
+  readonly subject: GeoSpecNativeSubject
+
+// Complete native minimum and ordered finite witnesses in canonical millimetres/Z-up
+MinimumDistanceFact: {
+    readonly source: 'ap242';
+    readonly assurance: 'exact-brep';
+    readonly unit: 'mm';
+    readonly coordinateSystem: 'z-up';
+    readonly subjectHash: string;
+    readonly algorithmProfile: 'geospec-minimum-distance-v1';
+    readonly occurrences: readonly [string, string];
+    readonly distance: number;
+    readonly points: readonly [readonly [number, number, number], readonly [number, number, number]];
+}
+
+  readonly source: 'ap242'
+
+  readonly assurance: 'exact-brep'
+
+  readonly unit: 'mm'
+
+  readonly coordinateSystem: 'z-up'
+
+  readonly subjectHash: string
+
+  readonly algorithmProfile: 'geospec-minimum-distance-v1'
+
+  readonly occurrences: readonly [string, string]
+
+  readonly distance: number
+
+  readonly points: readonly [readonly [number, number, number], readonly [number, number, number]]
+
+// Complete AP242 minimum over two subject-bound occurrence paths
+MinimumDistanceQuery: {
+    readonly capability: 'minimumDistance';
+    readonly subject: GeoSpecNativeSubject;
+    readonly payload: {
+        readonly pair: readonly [{
+            readonly occurrencePath: string;
+        }, {
+            readonly occurrencePath: string;
+        }];
+    };
+}
+
+  readonly capability: 'minimumDistance'
+
+  readonly subject: GeoSpecNativeSubject
+
+  readonly payload: {
+          readonly pair: readonly [{
+              readonly occurrencePath: string;
+          }, {
+              readonly occurrencePath: string;
+          }];
+      }
+
+// Geometry refusal and infrastructure interruption never masquerade as facts
+MinimumDistanceResult: {
+    readonly status: 'complete';
+    readonly fact: MinimumDistanceFact;
+} | {
+    readonly status: 'refused';
+    readonly code: 'unsupported-evidence' | 'invalid-selection' | 'work-limit' | 'analysis-limit' | 'resource-limit';
+    readonly message: string;
+} | {
+    readonly status: 'interrupted';
+    readonly code: 'cancelled' | 'executor-exited' | 'deadline' | 'engine-error';
+    readonly message: string;
+}
+
+  readonly status: 'complete'
+
+// Flat native query transport options
+GeoSpecNativeQueryOptions: Omit<GeoSpecNativeClaimOptions, 'arguments' | 'capability' | 'kind' | 'polarity'> & {
+    readonly capability: GeoSpecQueryCapability | 'minimumDistance';
+    readonly payload?: unknown;
+}
+
+  readonly engine: GeoSpecNativeEngine
+
+  readonly claimId: string
+
+  readonly evidenceProfile?: GeoSpecNativeEvidenceProfile
+
+  readonly subjectSlot: string
+
+  readonly workUnitLimit: number
+
+  // The host's largest authored budget, reported as `details.maximumLimit` on `MATCHER_TIMEOUT`
+  readonly maximumWorkUnitLimit?: number
+
+  readonly subject: GeoSpecNativeSubject
+
+  readonly capability: GeoSpecQueryCapability | 'minimumDistance'
+
+  readonly payload?: unknown
+
+// Existing positive-only ancillary operations owned by the native core
+GeoSpecQueryCapability: Exclude<(typeof geoSpecQueryCapabilities)[number], 'minimumDistance'>
+
+// Explicit support state for one source-attributed inventory field
+GeoSpecPmiField: {
+    readonly status: 'supported' | 'missing' | 'invalid' | 'ambiguous' | 'unsupported';
+    readonly value: Value | null;
+    readonly reason: string | null;
+}
+
+  readonly status: 'supported' | 'missing' | 'invalid' | 'ambiguous' | 'unsupported'
+
+  readonly value: Value | null
+
+  readonly reason: string | null
+
+// Original Part21 entity ID and exact source argument tokens
+GeoSpecPmiRawEntity: {
+    readonly sourceId: number;
+    readonly kind: string;
+    readonly arguments: readonly string[];
+}
+
+  readonly sourceId: number
+
+  readonly kind: string
+
+  readonly arguments: readonly string[]
+
+// Source-authored scalar and Rust-normalized reduced rational millimetres
+GeoSpecPmiNumber: {
+    readonly sourceId: number;
+    readonly authoredText: string;
+    readonly unitId: number;
+    readonly unitRecords: readonly GeoSpecPmiRawEntity[];
+    readonly millimetres: string;
+    readonly name: string;
+}
+
+  readonly sourceId: number
+
+  readonly authoredText: string
+
+  readonly unitId: number
+
+  readonly unitRecords: readonly GeoSpecPmiRawEntity[]
+
+  readonly millimetres: string
+
+  readonly name: string
+
+// A uniquely forward-transferred face
+GeoSpecPmiFaceAssociation: {
+    readonly sourceFaceId: number;
+    readonly occurrenceRoute: readonly number[];
+    readonly occurrence: number | null;
+    readonly publicFaceOrdinal: number;
+}
+
+  readonly sourceFaceId: number
+
+  readonly occurrenceRoute: readonly number[]
+
+  readonly occurrence: number | null
+
+  readonly publicFaceOrdinal: number
+
+// One ordered role reference, including incomplete source/transfer evidence
+GeoSpecPmiShapeReference: {
+    readonly sourceAspectId: number | null;
+    readonly sourceUsageIds: readonly number[];
+    readonly sourceItemIds: readonly number[];
+    readonly requestedRoute: GeoSpecPmiField<readonly number[]>;
+    readonly associations: GeoSpecPmiField<readonly GeoSpecPmiFaceAssociation[]>;
+}
+
+  readonly sourceAspectId: number | null
+
+  readonly sourceUsageIds: readonly number[]
+
+  readonly sourceItemIds: readonly number[]
+
+  readonly requestedRoute: GeoSpecPmiField<readonly number[]>
+
+  readonly associations: GeoSpecPmiField<readonly GeoSpecPmiFaceAssociation[]>
+
+// Normalized authored limits
+GeoSpecPmiLimits: {
+    readonly lowerMillimetres: string;
+    readonly upperMillimetres: string;
+    readonly basis: 'authored-limits' | 'nominal-plus-minus';
+}
+
+  readonly lowerMillimetres: string
+
+  readonly upperMillimetres: string
+
+  readonly basis: 'authored-limits' | 'nominal-plus-minus'