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

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

@@ -1,219 +1,6 @@
 # geospec — Types (3)
 
-31 top-level symbols. Signatures are verbatim typescript.
-
-// 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'
+21 top-level symbols. Signatures are verbatim typescript.
 
 // Source record preserving semantic/presentation separation and ordered roles
 GeoSpecPmiRecord: {
@@ -405,6 +192,8 @@ GeoSpecCliHost: {
         configPath: string | undefined;
         workers: number | undefined;
         shardTimeout: number | undefined;
+        /** In-memory spec sources keyed by project-rooted path, served in place of the disk (`geospec check`). */
+        sources?: Readonly<Record<string, string>>;
     }): GeoSpecRunner;
 }
 
@@ -437,6 +226,8 @@ GeoSpecCliHost: {
           configPath: string | undefined;
           workers: number | undefined;
           shardTimeout: number | undefined;
+          /** In-memory spec sources keyed by project-rooted path, served in place of the disk (`geospec check`). */
+          sources?: Readonly<Record<string, string>>;
       }): GeoSpecRunner;
 
 // Options for {@link createNodeGeoSpecCliHost}
@@ -448,6 +239,8 @@ NodeGeoSpecCliHostOptions: {
      * can run a project with no `geospec.config.*` (see `GeoSpecExporterModule` in `geospec/runner/node`).
      */
     readonly exporterModules?: readonly string[];
+    /** URL of a module each pool worker imports for its module VM (see `GeoSpecModuleVmModule` in `geospec/runner`). */
+    readonly moduleVmModule?: string;
 }
 
   // Report sink used by embedding hosts and tests
@@ -456,6 +249,9 @@ NodeGeoSpecCliHostOptions: {
   // URLs of modules each pool worker imports for exporters that precede the config's, so a host such as `tau test` can run a project with no `geospec.config.*` (see `GeoSpecExporterModule` in `geospec/runner/node`)
   readonly exporterModules?: readonly string[]
 
+  // URL of a module each pool worker imports for its module VM (see `GeoSpecModuleVmModule` in `geospec/runner`)
+  readonly moduleVmModule?: string
+
 // Installed Vitest matcher map and lifecycle settlement hook
 GeoSpecVitestAdapter: {
     readonly matchers: GeoSpecVitestMatcherMap;
@@ -467,12 +263,77 @@ GeoSpecVitestAdapter: {
   // GeoSpecVitestAdapter.flush (method)
   flush(): Promise<void>;
 
+// The installed matchers plus the project's model loader
+GeoSpecVitestProject: GeoSpecVitestAdapter & {
+    /** Load a model through the config's exporters; its subjects are released after the file. */
+    readonly loadModel: (options: LoadModelOptions) => Promise<GeoSpecSubject>;
+    /** The config file that was read, when the project has one. */
+    readonly configPath: string | undefined;
+    /** The build the created engine runs on; absent for a caller-owned engine. */
+    readonly binding: GeoSpecEngineBinding | undefined;
+}
+
+  readonly matchers: GeoSpecVitestMatcherMap
+
+  // GeoSpecVitestProject.flush (method)
+  flush(): Promise<void>;
+
+  // Load a model through the config's exporters
+  readonly loadModel: (options: LoadModelOptions) => Promise<GeoSpecSubject>
+
+  // The config file that was read, when the project has one
+  readonly configPath: string | undefined
+
+  // The build the created engine runs on
+  readonly binding: GeoSpecEngineBinding | undefined
+
+// Options for {@link setupGeoSpecVitestProject}
+SetupGeoSpecVitestProjectOptions: Omit<GeoSpecAssertionClientOptions, 'engine' | 'maximumWorkUnitLimit'> & {
+    /** Absolute project root: `loadModel({ file })` resolves against it and its `geospec.config.*` is read. */
+    readonly projectPath: string;
+    /** Explicit config file, resolved relative to the project unless absolute. */
+    readonly configPath?: string;
+    /** Fields that replace the config's whole, as a CLI flag does: `exporters` and `testTimeout` apply here. */
+    readonly overrides?: Pick<GeoSpecConfig, 'exporters' | 'testTimeout'>;
+    /**
+     * A caller-owned engine, kept open after the file. Omitted creates this process's engine (the native addon, else
+     * the WASM build) and closes it after the file.
+     */
+    readonly engine?: GeoSpecNativeModelEngine;
+}
+
+  readonly claimId?: (matcher: GeoSpecMatcherName, sequence: number) => string
+
+  // Success-evidence profile of every claim and query
+  readonly evidenceProfile?: GeoSpecNativeEvidenceProfile
+
+  readonly subjectSlot?: string
+
+  readonly workUnitLimit?: number
+
+  // Absolute project root
+  readonly projectPath: string
+
+  // Explicit config file, resolved relative to the project unless absolute
+  readonly configPath?: string
+
+  // Fields that replace the config's whole, as a CLI flag does
+  readonly overrides?: Pick<GeoSpecConfig, 'exporters' | 'testTimeout'>
+
+  // A caller-owned engine, kept open after the file
+  readonly engine?: GeoSpecNativeModelEngine
+
 // Options for {@link readGeoSpecConfig}
 ReadGeoSpecConfigOptions: {
     /** The project filesystem; paths are rooted, as the spec VM reads them. */
     readonly filesystem: VmFileSystem;
     /** Rooted directory holding the config, in the filesystem's spelling: `''` for its root, else `'sub/dir'`. */
     readonly projectPath: string;
+    /**
+     * Module VM factory; defaults to GeoSpec's plain VM (native esbuild on Node, refused elsewhere). A host that bundles
+     * in a browser injects its own; Tau injects `createEsbuildModuleVm`.
+     */
+    readonly createModuleVm?: CreateModuleVm;
 }
 
   // The project filesystem
@@ -481,6 +342,9 @@ ReadGeoSpecConfigOptions: {
   // Rooted directory holding the config, in the filesystem's spelling
   readonly projectPath: string
 
+  // Module VM factory
+  readonly createModuleVm?: CreateModuleVm
+
 // Outcome of {@link readGeoSpecConfig}
 ReadGeoSpecConfigResult: {
     readonly status: 'absent';
@@ -502,7 +366,7 @@ ReadGeoSpecConfigResult: {
   readonly status: 'absent'
 
 // Trusted project configuration using existing discovery and runner options
-// Remarks: Omitted values keep their existing owner's defaults. Defined overrides replace whole fields, including empty arrays and false. Existing discovery currently treats an absent or empty include array as its default pattern. Preserving [] here does not change that consumer behavior. This is configuration data, not a canonical engine plan or a geometry result.
+// Remarks: Omitted values keep their existing owner's defaults. Defined overrides replace whole fields, including empty arrays and false. Existing discovery treats an absent or empty include array as its default pattern. Preserving [] here does not change that consumer behavior. This is configuration data, not a canonical engine plan or a geometry result.
 GeoSpecConfig: {
     include?: readonly string[];
     exclude?: readonly string[];