geospec 0.1.0-beta.7 → 0.1.0-beta.8

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

@@ -1,6 +1,6 @@
 # geospec — Types (2)
 
-63 top-level symbols. Signatures are verbatim typescript.
+61 top-level symbols. Signatures are verbatim typescript.
 
 // Inline code-CAD model load options
 LoadModelCodeOptions: {
@@ -12,13 +12,9 @@ LoadModelCodeOptions: {
     rootDir?: never;
     /** Geometry format to export. Defaults to `glb`. */
     format?: GeoSpecModelFormat;
-    /** Explicit parameters passed to the runtime. */
+    /** Explicit parameters passed to the exporter. */
     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. */
+    /** Absolute project root passed to the exporter. */
     projectPath?: string;
     /** STEP reader strategy used for STEP exports. */
     stepStreaming?: StepStreamingMode;
@@ -35,12 +31,11 @@ LoadModelCodeOptions: {
      */
     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.
+     * 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;
 }
@@ -57,16 +52,10 @@ LoadModelCodeOptions: {
   // Geometry format to export
   format?: GeoSpecModelFormat
 
-  // Explicit parameters passed to the runtime
+  // Explicit parameters passed to the exporter
   parameters?: Record<string, unknown>
 
-  // Runtime client or lazy runtime factory
-  runtime?: GeoSpecRuntimeClient | GeoSpecRuntimeClientFactory
-
-  // Source-specific runtime adapters, e.g
-  sourceAdapters?: readonly GeoSpecRuntimeSourceAdapter[]
-
-  // Project root used by runtime integrations
+  // Absolute project root passed to the exporter
   projectPath?: string
 
   // STEP reader strategy used for STEP exports
@@ -84,7 +73,7 @@ LoadModelCodeOptions: {
   // Default work-unit budget for every claim on this subject
   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
+  // 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
@@ -100,16 +89,12 @@ LoadModelFileOptions: {
      * evidence.
      */
     rootDir?: string;
-    /** Project root used by runtime integrations. */
+    /** Absolute project root passed to the exporter. */
     projectPath?: string;
     /** Geometry format to export. Defaults to `glb`. */
     format?: GeoSpecModelFormat;
-    /** Explicit parameters passed to the runtime. */
+    /** Explicit parameters passed to the exporter. */
     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. */
@@ -125,12 +110,11 @@ LoadModelFileOptions: {
      */
     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.
+     * 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;
 }
@@ -141,21 +125,15 @@ LoadModelFileOptions: {
   // Project-relative folder `file` resolves in, for a suite that loads from somewhere other than the project root
   rootDir?: string
 
-  // Project root used by runtime integrations
+  // Absolute project root passed to the exporter
   projectPath?: string
 
   // Geometry format to export
   format?: GeoSpecModelFormat
 
-  // Explicit parameters passed to the runtime
+  // Explicit parameters passed to the exporter
   parameters?: Record<string, unknown>
 
-  // Runtime client or lazy runtime factory
-  runtime?: GeoSpecRuntimeClient | GeoSpecRuntimeClientFactory
-
-  // Source-specific runtime adapters, e.g
-  sourceAdapters?: readonly GeoSpecRuntimeSourceAdapter[]
-
   // STEP reader strategy used for STEP exports
   stepStreaming?: StepStreamingMode
 
@@ -171,7 +149,7 @@ LoadModelFileOptions: {
   // Default work-unit budget for every claim on this subject
   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
+  // 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}
@@ -183,7 +161,7 @@ LoadModelOptions: LoadModelSourceOptions | LoadModelCodeOptions<Code> | LoadMode
   // Geometry format to export
   format?: GeoSpecModelFormat
 
-  // Explicit parameters passed to the runtime
+  // Explicit parameters passed to the exporter
   parameters?: Record<string, unknown>
 
   // STEP reader strategy used for STEP exports
@@ -283,6 +261,38 @@ LoadModelSourceOptions: {
   // 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>>;
+}
+
+  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>>
+
 // Collects suites, tests, assertions, and async completion state for one GeoSpec module execution
 GeoSpecCollector: {
     tests: GeoSpecTestCase[];
@@ -316,17 +326,11 @@ GeoSpecCollector: {
 
 // Per-module collector configuration
 GeoSpecCollectorOptions: {
-    matcherWallBackstop?: number;
-    forensic?: boolean;
     nativeAssertions: GeoSpecAssertionClientOptions;
     /** Observes each selected test as it starts and settles, for host progress reporting. */
     onTestEvent?: (event: GeoSpecTestEvent) => void;
 }
 
-  matcherWallBackstop?: number
-
-  forensic?: boolean
-
   nativeAssertions: GeoSpecAssertionClientOptions
 
   // Observes each selected test as it starts and settles, for host progress reporting
@@ -538,10 +542,6 @@ RunGeoSpecModuleOptions: {
     testNamePattern?: string | RegExp;
     /** Timeout for async test callbacks, in milliseconds. */
     testTimeout?: number;
-    /** Milliseconds. Non-verdict matcher infrastructure backstop. */
-    matcherWallBackstop?: number;
-    /** Emit structured forensic events for this run. */
-    forensic?: boolean;
     /** Observes each selected test as it starts and settles, for host progress reporting. */
     onTestEvent?: (event: GeoSpecTestEvent) => void;
     /**
@@ -579,12 +579,6 @@ RunGeoSpecModuleOptions: {
   // Timeout for async test callbacks, in milliseconds
   testTimeout?: number
 
-  // Milliseconds
-  matcherWallBackstop?: number
-
-  // Emit structured forensic events for this run
-  forensic?: boolean
-
   // Observes each selected test as it starts and settles, for host progress reporting
   onTestEvent?: (event: GeoSpecTestEvent) => void
 
@@ -655,8 +649,8 @@ CreateGeoSpecNativeModelLoaderOptions: {
     readonly format?: Extract<GeoSpecModelFormat, 'glb' | 'step' | 'stp'>;
     readonly projectPath?: string;
     readonly readSource?: GeoSpecNativeSourceReader;
-    readonly runtime?: GeoSpecRuntimeClient | GeoSpecRuntimeClientFactory;
-    readonly sourceAdapters?: readonly GeoSpecRuntimeSourceAdapter[];
+    /** Model exporters for source-kind files; the first whose `extensions` claim the file exports it. */
+    readonly exporters?: readonly GeoSpecModelExporter[];
     /**
      * 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
@@ -680,9 +674,8 @@ CreateGeoSpecNativeModelLoaderOptions: {
 
   readonly readSource?: GeoSpecNativeSourceReader
 
-  readonly runtime?: GeoSpecRuntimeClient | GeoSpecRuntimeClientFactory
-
-  readonly sourceAdapters?: readonly GeoSpecRuntimeSourceAdapter[]
+  // Model exporters for source-kind files
+  readonly exporters?: readonly GeoSpecModelExporter[]
 
   // Subject handles carried between the release scopes of loaders that share one engine, keyed by subjectHash
   readonly carried?: Map<string, unknown>
@@ -704,7 +697,7 @@ GeoSpecNativeLoadModelOptions: LoadModelOptions<Code> & {
   // Geometry format to export
   format?: GeoSpecModelFormat
 
-  // Explicit parameters passed to the runtime
+  // Explicit parameters passed to the exporter
   parameters?: Record<string, unknown>
 
   // STEP reader strategy used for STEP exports
@@ -751,7 +744,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. 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.
+// 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.
 GeoSpecNativeModelLoader: <Code extends Record<string, string> = Record<string, string>>(options: GeoSpecNativeLoadModelOptions<Code>) => Promise<GeoSpecNativeModelSubject>
 
 // Subject identity returned by native STEP/GLB admission
@@ -787,7 +780,7 @@ 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.
+     * subjects this scope did not load again), then close every exporter it exported through.
      *
      * Await the intended complete load chain before final release, and await
      * this method before closing the caller-owned engine. Calls after it returns
@@ -811,16 +804,12 @@ GeoSpecPoolHostMessage: {
     shard: GeoSpecPoolShard;
     testNamePattern?: string;
     testTimeout?: number;
-    matcherWallBackstop?: number;
-    forensic?: boolean;
 } | {
     /** List-only collection pass: register tests, run no bodies (R3 splitting). */
     type: 'list-tests';
     shardId: number;
     file: string;
     testTimeout?: number;
-    matcherWallBackstop?: number;
-    forensic?: boolean;
 } | {
     type: 'shutdown';
 }
@@ -884,12 +873,6 @@ GeoSpecPoolWorkerMessage: {
     type: 'file-start';
     shardId: number;
     file: string;
-} | {
-    type: 'forensic';
-    shardId: number;
-    name: string;
-    value: number;
-    unit: 'milliseconds' | 'count';
 } | {
     type: 'tests-listed';
     shardId: number;
@@ -918,25 +901,6 @@ GeoSpecPoolWorkerMessage: {
 
   type: 'ready'
 
-// One structured forensic measurement emitted by a runner
-GeoSpecForensicEvent: {
-    type: 'forensic';
-    name: string;
-    value: number;
-    unit: 'milliseconds' | 'count';
-    shardId?: number;
-}
-
-  type: 'forensic'
-
-  name: string
-
-  value: number
-
-  unit: 'milliseconds' | 'count'
-
-  shardId?: number
-
 // Public GeoSpec runner lifecycle surface
 GeoSpecRunner: {
     /** Execute GeoSpec files and return a compact aggregate result. */
@@ -994,14 +958,14 @@ GeoSpecRunnerEvent: {
 } | {
     type: 'run-complete';
     result: GeoSpecRunnerResult;
-} | GeoSpecForensicEvent | {
+} | {
     type: 'abort';
     reason?: string;
 } | {
     type: 'close';
 }
 
-  type: 'forensic'
+  type: 'run-start'
 
 // One GeoSpec test file executed by a worker-style runner
 GeoSpecRunnerFileResult: {
@@ -1113,16 +1077,12 @@ GeoSpecRunnerRunOptions: {
     testNamePattern?: string | RegExp;
     /** Timeout for each async test callback, in milliseconds. */
     testTimeout?: number;
-    /** Non-verdict matcher wall backstop. Milliseconds. */
-    matcherWallBackstop?: number;
     /**
      * Engine work-unit budget for this run's claims, replacing the runner's
      * `nativeAssertions.workUnitLimit`. A `loadModel` or `expectGeo` budget still
      * wins for its own claims.
      */
     workUnitLimit?: number;
-    /** Emit structured forensic measurements for this run. */
-    forensic?: boolean;
     /**
      * Stop after the first failing file (R1). Interactive fail-fast only —
      * never the default for reward runs, which want the complete red set.
@@ -1139,18 +1099,137 @@ GeoSpecRunnerRunOptions: {
   // Timeout for each async test callback, in milliseconds
   testTimeout?: number
 
-  // Non-verdict matcher wall backstop
-  matcherWallBackstop?: number
-
   // Engine work-unit budget for this run's claims, replacing the runner's `nativeAssertions.workUnitLimit`
   workUnitLimit?: number
 
-  // Emit structured forensic measurements for this run
-  forensic?: boolean
-
   // Stop after the first failing file (R1)
   bail?: boolean
 
+// Everything the pool needs that differs between Node and the browser
+GeoSpecPoolOptions: {
+    /** Spawn one worker running `startGeoSpecPoolWorkerHost`. */
+    createWorker: () => GeoSpecPoolWorkerHandle | Promise<GeoSpecPoolWorkerHandle>;
+    /** Optional one-time worker initialization performed after its ready signal. */
+    initializeWorker?: (worker: GeoSpecPoolWorkerHandle) => Promise<void> | void;
+    /** Wait for each native worker's cleanup acknowledgement before terminating it. */
+    gracefulShutdown?: boolean;
+    /** Worker count. Omit to let the caller's host auto-size before calling. */
+    workers: number;
+    /** Optional scheduling telemetry. Absent = declared order, no memory class. */
+    timings?: ShardTimings;
+    /** Per-shard non-verdict watchdog, milliseconds (R11). */
+    shardTimeout?: number;
+    /** Split files whose recorded duration exceeds this. Milliseconds. */
+    splitThreshold?: number;
+}
+
+  // Spawn one worker running `startGeoSpecPoolWorkerHost`
+  createWorker: () => GeoSpecPoolWorkerHandle | Promise<GeoSpecPoolWorkerHandle>
+
+  // Optional one-time worker initialization performed after its ready signal
+  initializeWorker?: (worker: GeoSpecPoolWorkerHandle) => Promise<void> | void
+
+  // Wait for each native worker's cleanup acknowledgement before terminating it
+  gracefulShutdown?: boolean
+
+  // Worker count
+  workers: number
+
+  // Optional scheduling telemetry
+  timings?: ShardTimings
+
+  // Per-shard non-verdict watchdog, milliseconds (R11)
+  shardTimeout?: number
+
+  // Split files whose recorded duration exceeds this
+  splitThreshold?: number
+
+// One shard's recorded cost
+ShardTiming: {
+    /** Wall duration of the last recorded run, in milliseconds. */
+    durationMs: number;
+    /** Highest RSS observed for this shard, in bytes. Monotonic. */
+    peakRssBytes: number;
+}
+
+  // Wall duration of the last recorded run, in milliseconds
+  durationMs: number
+
+  // Highest RSS observed for this shard, in bytes
+  peakRssBytes: number
+
+// A mutable timings table
+ShardTimings: {
+    /** Merge one observation. Peak RSS only ever grows. */
+    record(shard: string, timing: ShardTiming): void;
+    /** The hint for one shard, or `undefined` when unknown. */
+    read(shard: string): ShardTiming | undefined;
+    /** Every recorded shard, sorted by descending duration (longest-first). */
+    longestFirst(): string[];
+    /** Persist the table. Failure is silent: telemetry never fails a run. */
+    save(): void;
+}
+
+  // Merge one observation
+  // ShardTimings.record (method)
+  record(shard: string, timing: ShardTiming): void;
+
+  // The hint for one shard, or `undefined` when unknown
+  // ShardTimings.read (method)
+  read(shard: string): ShardTiming | undefined;
+
+  // Every recorded shard, sorted by descending duration (longest-first)
+  // ShardTimings.longestFirst (method)
+  longestFirst(): string[];
+
+  // Persist the table
+  // ShardTimings.save (method)
+  save(): void;
+
+// Options accepted by {@link startGeoSpecPoolWorkerHost}
+GeoSpecPoolWorkerHostOptions: {
+    /** Filesystem containing the project and test modules. */
+    filesystem: GeoSpecRunnerOptions['filesystem'];
+    /** Native assertion client shared with this worker's model admissions. */
+    nativeAssertions: GeoSpecRunnerOptions['nativeAssertions'];
+    /** Managed native admissions, released after every shard and collection pass and before shutdown. */
+    nativeModelLoader: ManagedGeoSpecNativeModelLoader;
+    /** Additional in-memory modules made available to the VM. */
+    builtinModules?: GeoSpecRunnerOptions['builtinModules'];
+    /** 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. */
+    measureMemoryBytes?: () => number | undefined;
+    /** Release platform resources on shutdown, after the native subjects are released. */
+    onShutdown?: () => Promise<void> | void;
+}
+
+  // Filesystem containing the project and test modules
+  filesystem: GeoSpecRunnerOptions['filesystem']
+
+  // Native assertion client shared with this worker's model admissions
+  nativeAssertions: GeoSpecRunnerOptions['nativeAssertions']
+
+  // Managed native admissions, released after every shard and collection pass and before shutdown
+  nativeModelLoader: ManagedGeoSpecNativeModelLoader
+
+  // Additional in-memory modules made available to the VM
+  builtinModules?: GeoSpecRunnerOptions['builtinModules']
+
+  // 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)
+  measureMemoryBytes?: () => number | undefined
+
+  // Release platform resources on shutdown, after the native subjects are released
+  onShutdown?: () => Promise<void> | void
+
 // Runner-independent native assertion client
 GeoSpecAssertionClient: {
     /**
@@ -1414,114 +1493,3 @@ GeoSpecPmiFaceAssociation: {
   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'
-
-// Source record preserving semantic/presentation separation and ordered roles
-GeoSpecPmiRecord: {
-    readonly sourceId: number;
-    readonly family: 'dimension' | 'datum' | 'tolerance' | 'presentation';
-    readonly channel: 'semantic' | 'presentation';
-    readonly kind: string;
-    readonly name: GeoSpecPmiField<string>;
-    readonly first: readonly GeoSpecPmiShapeReference[];
-    readonly second: readonly GeoSpecPmiShapeReference[];
-    readonly numbers: GeoSpecPmiField<readonly GeoSpecPmiNumber[]>;
-    readonly limits: GeoSpecPmiField<GeoSpecPmiLimits>;
-    readonly interpretation: GeoSpecPmiField<string>;
-    readonly raw: readonly GeoSpecPmiRawEntity[];
-}
-
-  readonly sourceId: number
-
-  readonly family: 'dimension' | 'datum' | 'tolerance' | 'presentation'
-
-  readonly channel: 'semantic' | 'presentation'
-
-  readonly kind: string
-
-  readonly name: GeoSpecPmiField<string>
-
-  readonly first: readonly GeoSpecPmiShapeReference[]
-
-  readonly second: readonly GeoSpecPmiShapeReference[]
-
-  readonly numbers: GeoSpecPmiField<readonly GeoSpecPmiNumber[]>
-
-  readonly limits: GeoSpecPmiField<GeoSpecPmiLimits>
-
-  readonly interpretation: GeoSpecPmiField<string>
-
-  readonly raw: readonly GeoSpecPmiRawEntity[]
-
-// Positive-only inventory value inside the ordinary canonical query report
-GeoSpecPmiInventory: {
-    readonly contract: 'geospec.pmi.inventory/v1';
-    readonly status: 'semantic' | 'graphical-only' | 'empty';
-    readonly fileSchema: string;
-    readonly editionValidation: 'not-validated';
-    readonly records: readonly GeoSpecPmiRecord[];
-}
-
-  readonly contract: 'geospec.pmi.inventory/v1'
-
-  readonly status: 'semantic' | 'graphical-only' | 'empty'
-
-  readonly fileSchema: string
-
-  readonly editionValidation: 'not-validated'
-
-  readonly records: readonly GeoSpecPmiRecord[]
-
-// Strict inventory output limits
-GeoSpecPmiQueryPayload: {
-    readonly maxRecords?: number;
-    readonly maxOutputBytes?: number;
-}
-
-  readonly maxRecords?: number
-
-  readonly maxOutputBytes?: number
-
-// Complete inventory value
-GeoSpecPmiQueryValue: {
-    readonly inventory: GeoSpecPmiInventory;
-    readonly subjectHash: string;
-    readonly provenance: Readonly<Record<string, unknown>>;
-}
-
-  readonly inventory: GeoSpecPmiInventory
-
-  readonly subjectHash: string
-
-  readonly provenance: Readonly<Record<string, unknown>>