geospec 0.0.0 → 0.1.0-beta.2

package/dist/runner/native/native-pool-grants.d.mts

@@ -0,0 +1,21 @@
+//#region src/runner/native/native-pool-grants.d.ts
+/** Deterministic caller-inclusive permits for the host-composed compiled worker pool. @module */
+/**
+ * Assign a bounded CPU budget across already-selected worker isolates.
+ * The omitted budget is one permit per worker. A native pool must pass each
+ * returned grant to the engine it constructs inside the corresponding worker.
+ * A grant above one is admissible only for an engine with its own OCCT
+ * library instance: native workers that are threads of one process share one,
+ * so such a pool must use one worker or one permit per worker.
+ *
+ * @param options - Worker count, optional total budget, and host CPU cap.
+ * @returns Grants in worker creation order.
+ * @public
+ */
+declare const allocateNativePoolGrants: (options: {
+  workers: number;
+  budget?: number;
+  hostCap: number;
+}) => readonly number[];
+//#endregion
+export { allocateNativePoolGrants };

package/dist/runner/native/native-pool-grants.mjs

@@ -0,0 +1 @@
+const e=e=>{let{workers:t,hostCap:n}=e,r=e.budget??t;if(!Number.isSafeInteger(t)||!Number.isSafeInteger(r)||!Number.isSafeInteger(n)||t<1||r<t||r>n)throw RangeError(`Native pool requires positive workers and a caller-inclusive budget between workers and the host cap.`);let i=Math.floor(r/t),a=r%t;return Array.from({length:t},(e,t)=>i+ +(t<a))};export{e as allocateNativePoolGrants};

package/dist/runner/native/native-serial-runner.d.mts

@@ -0,0 +1,29 @@
+import { CreateGeoSpecNativeModelLoaderOptions, GeoSpecNativeModelEngine, ManagedGeoSpecNativeModelLoader } from "../../model/native-model-loader.mjs";
+import { GeoSpecAssertionClientOptions } from "../../assertion-client/client.mjs";
+import "../../assertion-client/index.mjs";
+import { GeoSpecRunner, GeoSpecRunnerOptions } from "../worker/runner-types.mjs";
+import "../worker/index.mjs";
+//#region src/runner/native/native-serial-runner.d.ts
+/** Native assertion options whose engine can also admit and release subjects. @public */
+type GeoSpecNativeRunnerAssertions = Omit<GeoSpecAssertionClientOptions, 'engine'> & {
+  readonly engine: GeoSpecNativeModelEngine;
+};
+/** Options for the native serial runner. @public */
+type GeoSpecNativeRunnerOptions = Omit<GeoSpecRunnerOptions, 'nativeAssertions' | 'nativeModelLoader'> & {
+  /** Actual protocol-3 engine used by authored assertions. */
+  readonly nativeAssertions: GeoSpecNativeRunnerAssertions;
+  /** Optional managed loader; the runner releases its subjects after every run. */
+  readonly nativeModelLoader?: ManagedGeoSpecNativeModelLoader;
+  /** Defaults used when the runner constructs its own native loader. */
+  readonly model?: Omit<CreateGeoSpecNativeModelLoaderOptions, 'engine'>;
+};
+/**
+ * Compose compiled assertion and model bindings with the SDK's serial lifecycle.
+ *
+ * @param options - VM filesystem, native engine/client options and model defaults.
+ * @returns The ordinary GeoSpec runner lifecycle and event contract.
+ * @public
+ */
+declare const createNativeGeoSpecRunner: (options: GeoSpecNativeRunnerOptions) => GeoSpecRunner;
+//#endregion
+export { GeoSpecNativeRunnerAssertions, GeoSpecNativeRunnerOptions, createNativeGeoSpecRunner };

package/dist/runner/native/native-serial-runner.mjs

@@ -0,0 +1 @@
+import{createGeoSpecNativeModelLoader as e}from"../../model/native-model-loader.mjs";import{createSerialGeoSpecRunner as t}from"../worker/serial-runner.mjs";const n=new TextDecoder(`utf-8`,{fatal:!0}),r=(e,t)=>{let r=JSON.parse(n.decode(e));if(typeof r!=`object`||!r||!(`plan`in r))throw TypeError(`Native GeoSpec assertion requires a plan with admitted subjects.`);let{plan:i}=r;if(typeof i!=`object`||!i||!(`subjects`in i)||!Array.isArray(i.subjects)||i.subjects.length===0)throw TypeError(`Native GeoSpec assertion requires admitted subjects.`);for(let e of i.subjects){if(typeof e!=`object`||!e)throw TypeError(`Native GeoSpec assertion requires admitted subjects.`);let n=`subjectHash`in e;if(n===`contentHash`in e)throw TypeError(`Native GeoSpec assertion requires one admitted subject identity.`);let r=n?e.subjectHash:`contentHash`in e?e.contentHash:void 0;if(typeof r!=`string`||!t.has(r))throw TypeError(`Native GeoSpec subject was not admitted by this run.`)}},i=i=>{let a=i.nativeModelLoader??e({...i.model,engine:i.nativeAssertions.engine}),o=new Set,s=Object.assign(async e=>{let t=await a(e);return o.add(t.subjectHash),t},{async releaseAll(){try{await a.releaseAll()}finally{o.clear()}}}),c=i.nativeAssertions.engine,l={evaluateClaim(e){return r(e,o),c.evaluateClaim(e)},processRequest(e){let t=JSON.parse(n.decode(e));return typeof t==`object`&&t&&`method`in t&&t.method===`submitClaims`&&r(e,o),c.processRequest(e)},ingestSubject:(e,t,n)=>c.ingestSubject(e,t,n),subjectHandle:e=>c.subjectHandle(e),releaseSubject:e=>c.releaseSubject(e)},u=t({filesystem:i.filesystem,nativeAssertions:{...i.nativeAssertions,engine:l},nativeModelLoader:s,...i.builtinModules===void 0?{}:{builtinModules:i.builtinModules}});return{...u,async close(){try{await u.close()}finally{o.clear()}}}};export{i as createNativeGeoSpecRunner};

package/dist/runner/pool/pool-messages.d.mts

@@ -0,0 +1,94 @@
+import { GeoSpecRunResult } from "../types.mjs";
+//#region src/runner/pool/pool-messages.d.ts
+/** One schedulable work unit.
+ *
+ * @public
+ */
+type GeoSpecPoolShard = {
+  /** Stable shard id, unique within one pool run. */
+  id: number;
+  /** GeoSpec file this shard executes. */
+  file: string;
+  /** Exact-test pattern for split shards (R3: `(file, testNamePattern)` work units). */
+  testNamePattern?: string;
+};
+/** Host → worker messages. */
+/** @public */
+type GeoSpecPoolHostMessage = {
+  type: 'initialize';
+} | {
+  type: 'run-shard';
+  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';
+};
+/** Worker → host messages. */
+/** @public */
+type GeoSpecPoolWorkerMessage = {
+  type: 'ready';
+} | {
+  type: 'initialized';
+} | {
+  type: 'initialization-error';
+  message: string;
+} | {
+  type: 'file-start';
+  shardId: number;
+  file: string;
+} | {
+  type: 'forensic';
+  shardId: number;
+  name: string;
+  value: number;
+  unit: 'milliseconds' | 'count';
+} | {
+  type: 'tests-listed';
+  shardId: number;
+  file: string;
+  names: string[];
+} | {
+  type: 'list-error';
+  shardId: number;
+  file: string;
+  message: string;
+} | {
+  type: 'shard-complete';
+  shardId: number;
+  file: string;
+  result: GeoSpecRunResult;
+  durationMs: number;
+  primaryLoadKey?: string;
+  /** Worker-isolate resident memory at completion (heap + external), bytes. */
+  workerMemoryBytes?: number;
+} | {
+  type: 'shard-error';
+  shardId: number;
+  file: string;
+  message: string;
+};
+/** Minimal worker handle the host-agnostic pool drives (Node or Web Worker). */
+/** @public */
+type GeoSpecPoolWorkerHandle = {
+  postMessage(message: GeoSpecPoolHostMessage): void;
+  onMessage(listener: (message: GeoSpecPoolWorkerMessage) => void): void;
+  onExit(listener: (details: {
+    unexpected: boolean;
+    message?: string;
+  }) => void): void;
+  /** Hard-stop the worker thread (R11 watchdog primitive). */
+  terminate(): Promise<void> | void;
+};
+//#endregion
+export { GeoSpecPoolHostMessage, GeoSpecPoolShard, GeoSpecPoolWorkerHandle, GeoSpecPoolWorkerMessage };

package/dist/runner/run-geospec-module.d.mts

@@ -0,0 +1,13 @@
+import { GeoSpecRunResult, RunGeoSpecModuleOptions } from "./types.mjs";
+//#region src/runner/run-geospec-module.d.ts
+/**
+ * Execute an ESM GeoSpec module using the shared Tau VM substrate.
+ *
+ * @param options - filesystem and test entry path.
+ * @returns collected test cases or structured VM issues.
+ *
+ * @public
+ */
+declare function runGeoSpecModule(options: RunGeoSpecModuleOptions): Promise<GeoSpecRunResult>;
+//#endregion
+export { runGeoSpecModule };

package/dist/runner/run-geospec-module.mjs

@@ -0,0 +1,47 @@
+import{bindGeoSpecSubject as e,rawSubjectResidency as t,resolveGeoSpecSubject as n}from"../model/subject.mjs";import{createGeoSpecAssertionClient as r}from"../assertion-client/client.mjs";import{GeoSpecModelLoadError as i}from"../model/errors.mjs";import{compileGeoSpecTestNamePattern as a,filterGeoSpecTests as o}from"./filter.mjs";import{createCollector as s}from"./collector.mjs";import{sha256Bytes as c}from"@taucad/runtime/kernel";import{createEsbuildModuleVm as l}from"@taucad/esbuild/vm";const u=`__GEOSPEC_RUN_BINDINGS__`,d=globalThis,f=()=>`geospec-${Date.now().toString(36)}-${Math.random().toString(36).slice(2)}`,p=e=>JSON.stringify(Object.entries(e.builtinModules??{}).sort(([e],[t])=>e.localeCompare(t)).map(([e,t])=>[e,t.version,t.globalName,t.code])),m=(e,t)=>e.byteLength===t.byteLength&&e.every((e,n)=>e===t[n]),h=(e,t)=>e instanceof Uint8Array&&t instanceof Uint8Array?m(e,t):e===t,g=async(e,{question:t,path:n})=>t===`exists`?e.exists(n):t===`utf8`?e.readFile(n,`utf8`):e.readFile(n),_=async(e,t)=>(await Promise.all(t.map(async t=>{try{return h(await g(e,t),t.answer)}catch{return!1}}))).every(Boolean),v=e=>{let t=new Map,n=!0,r=async(e,r,i)=>{try{let a=await i,o=t.get(`${e}:${r}`);return o===void 0?t.set(`${e}:${r}`,{question:e,path:r,answer:a instanceof Uint8Array?Uint8Array.from(a):a}):n&&=h(o.answer,a),a}catch(e){throw n=!1,e}};return{filesystem:{exists:async t=>r(`exists`,t,e.exists(t)),readFile:(async(t,n)=>n===`utf8`?r(`utf8`,t,e.readFile(t,`utf8`)):r(`bytes`,t,e.readFile(t))),writeFile:async(t,n)=>e.writeFile(t,n),ensureDir:async t=>e.ensureDir(t)},reads:()=>n?[...t.values()]:void 0,observed:()=>[...t.values()]}},y=async e=>{let t=e.bundleCache?.get(e.entryPath);if(!(t===void 0||t.builtinIdentity!==p(e)||!await _(e.filesystem,t.bundlerReads)))return t},b=()=>{let e=d[u];if(e)return e;let t=new Map;return d[u]=t,t},x=e=>`
+const getRunBinding = () => {
+  const binding = globalThis.${u}?.get(${JSON.stringify(e)});
+  if (!binding) {
+    throw new Error('GeoSpec runner binding is not active. Run the module through runGeoSpecModule().');
+  }
+  return binding;
+};
+`,S=e=>`
+${x(e)}
+
+export const describe = (name, fn) => getRunBinding().collector.describe(name, fn);
+describe.skip = (name, fn) => getRunBinding().collector.describeSkip(name, fn);
+
+export const it = (name, fn) => getRunBinding().collector.it(name, fn);
+it.skip = (name, fn) => getRunBinding().collector.itSkip(name, fn);
+
+export const test = it;
+export const expectGeo = (subject) => getRunBinding().collector.expectGeo(subject);
+`,C=e=>`
+${x(e)}
+export const GeoSpecModelLoadError = getRunBinding().geoSpecModelLoadError;
+
+export const loadModel = async (options) => {
+  const binding = getRunBinding();
+  const loader = binding.nativeModelLoader;
+  if (typeof loader !== 'function') {
+    throw new GeoSpecModelLoadError([
+      {
+        code: 'GEOSPEC_MODEL_LOADER_UNAVAILABLE',
+        severity: 'error',
+        message: 'No GeoSpec model loader is active for this runner.',
+        suggestion: 'Run this test through the GeoSpec CLI or Tau browser test runner.',
+      },
+    ]);
+  }
+  return loader(options);
+};
+
+export const createModelLoader = (defaults = {}) => {
+  const factory = getRunBinding().createModelLoader;
+  if (typeof factory !== 'function') {
+    throw new GeoSpecModelLoadError([{ code: 'GEOSPEC_MODEL_LOADER_UNAVAILABLE', severity: 'error', message: 'No managed GeoSpec model loader is active for this runner.' }]);
+  }
+  return factory(defaults);
+};
+`;async function w(m){let h=a(m.testNamePattern);if(!h.success)return{success:!1,issues:[h.issue]};let g=v(m.filesystem),_=await l({filesystem:g.filesystem}),x=s({...m.matcherWallBackstop===void 0?{}:{matcherWallBackstop:m.matcherWallBackstop},...m.forensic===void 0?{}:{forensic:m.forensic},nativeAssertions:m.nativeAssertions}),w=await y(m),T=f(),E=b(),D=new Set,O=[],k=async()=>{do{let e=[...D];await Promise.allSettled(e);for(let t of e)D.delete(t)}while(D.size>0)},A=m.nativeModelLoader,j=r(m.nativeAssertions),M=!0,N=A===void 0?void 0:n=>{let r=O.length,a=`${T}:load:${r+1}`;O.push({loadId:a,status:`unavailable`});let o=(async()=>{try{let i=await A(n),{load:o,...s}=i,c=t(i),l=o===void 0?void 0:{...structuredClone(o),loadId:a};return O[r]={loadId:a,status:l?.status??`unavailable`,subject:s,...l===void 0?{}:{evidence:l}},e({engine:m.nativeAssertions.engine,client:j,identity:s,...l===void 0?{}:{load:l},isLive:()=>M,...c===void 0?{}:{ensureResident:c}})}catch(e){throw O[r]={loadId:a,status:`failed`,error:e instanceof Error?e.message:String(e),...e instanceof i?{diagnostics:e.diagnostics}:{}},e}})();return D.add(o.catch(()=>void 0)),D.add(o),o};E.set(T,{collector:x,geoSpecModelLoadError:i,...N?{nativeModelLoader:N}:{},...N?{createModelLoader:t=>{if(t.engine!==void 0||t.readSource!==void 0)throw TypeError(`Authored VM model defaults cannot replace the admitting host.`);let r=0,i=new Set,a=new Set,o,s=async i=>{let o=r,s=await N({...t,...i}),c=n(s);return c.lease!==void 0&&a.add(c.lease),e({...c,isLive:()=>c.isLive()&&r===o})},c=e=>{let t=s(e);return i.add(t),t},l=async()=>{do{let e=[...i];await Promise.allSettled(e);for(let t of e)i.delete(t)}while(i.size>0);r+=1;let e=[];for(let t of a)try{t.dispose(),a.delete(t)}catch(t){e.push(t)}if(e.length>0)throw AggregateError(e,`GeoSpec model scope disposal failed.`)};return Object.assign(c,{dispose(){return o??=l().finally(()=>{o=void 0}),o}})}}:{}}),_.registerModule(`geospec`,{version:`0.0.0-poc`,code:S(T)}),_.registerModule(`geospec/model`,{version:`0.0.0-poc`,code:C(T)});for(let[e,t]of Object.entries(m.builtinModules??{}))_.registerModule(e,t);try{let e=w?.bundle??await _.bundle(m.entryPath);if(!e.success)return{success:!1,issues:e.issues,bundle:e};let t=g.reads();m.bundleCache!==void 0&&w===void 0&&t!==void 0&&m.bundleCache.set(m.entryPath,{builtinIdentity:p(m),runToken:T,bundle:e,bundlerReads:t});let n=await _.execute(w===void 0?e.code:e.code.replaceAll(w.runToken,T)),r=async()=>{let t={},n=g.reads()!==void 0;for(let e of w?.bundlerReads??g.observed()){if(e.question===`exists`||typeof e.answer==`boolean`)continue;let r=await c(typeof e.answer==`string`?new TextEncoder().encode(e.answer):e.answer);n&&=t[e.path]===void 0||t[e.path]===`sha256:${r}`,t[e.path]=`sha256:${r}`}let r=new Map(Object.entries(t));for(let e of O){let{evidence:t}=e;for(let e of t?.exportOptions===void 0?t?.artifacts??[]:[])if(e.sourcePath!==void 0){let t=`sha256:${e.sha256}`;n&&=!r.has(e.sourcePath)||r.get(e.sourcePath)===t,r.set(e.sourcePath,t)}if(t?.sourcePath!==void 0&&t.exportOptions===void 0){let e=t.artifacts[0];if(e!==void 0){let i=`sha256:${e.sha256}`;n&&=!r.has(t.sourcePath)||r.get(t.sourcePath)===i,r.set(t.sourcePath,i)}}for(let[t,i]of Object.entries(e.evidence?.sourceRevision?.files??{}))n&&=!r.has(t)||r.get(t)===i,r.set(t,i)}return{status:n?O.some(e=>e.status!==`complete`)?`unavailable`:`complete`:`mixed`,modules:[{entryPath:m.entryPath,bundleSha256:await c(new TextEncoder().encode(w===void 0?e.code:e.code.replaceAll(w.runToken,T))),files:t,consistent:n}],loads:O}},i=e=>({discovered:x.tests.length,selected:e,completed:x.tests.filter(e=>e.status!==`not-run`&&e.status!==`skipped`).length,passed:x.tests.filter(e=>e.status===`passed`).length,failed:x.tests.filter(e=>e.status===`failed`).length,unsupported:x.tests.filter(e=>e.status===`unsupported`).length,inconclusive:x.tests.filter(e=>e.status===`inconclusive`).length,skipped:x.tests.filter(e=>e.status===`skipped`).length,notRun:x.tests.filter(e=>e.status===`not-run`).length});if(!n.success)return await k(),{success:!1,issues:n.issues,bundle:e,tests:x.tests,accounting:i(0),lineage:await r()};if(m.collectOnly===!0)return await x.waitForCompletion(m.testTimeout,/(?!)/u),await k(),{success:!0,passed:!1,tests:x.tests,bundle:e,accounting:i(0),lineage:await r()};await x.waitForCompletion(m.testTimeout,h.pattern),await k();let a=o(x.tests,h.pattern),s=await r();return{success:!0,passed:s.status===`complete`&&a.every(e=>e.status===`passed`||e.status===`skipped`),tests:a,bundle:e,accounting:i(a.length),lineage:s}}finally{await k(),M=!1,E.delete(T),E.size===0&&Reflect.deleteProperty(d,u),_.dispose()}}export{w as runGeoSpecModule};