geospec-engine 0.0.0 → 0.1.0-next.19

package/dist/host-types.d.mts

@@ -0,0 +1,48 @@
+//#region src/host-types.d.ts
+/** Bytes accepted and returned by a GeoSpec host facade. @public */
+type HostBytes = Uint8Array<ArrayBuffer>;
+/** Stable protocol failure surfaced by every GeoSpec host facade. @public */
+declare class ProtocolError extends Error {
+  /** Machine-readable core error code. */
+  readonly code: string;
+  constructor(code: string, message: string, options?: ErrorOptions);
+}
+/** Byte-only stateful engine surface shared by Node and WASM hosts. @public */
+type HostEngine = {
+  /** Non-mutating cumulative diagnostics; absent on unqualified historical bindings. */
+  observations?: () => HostBytes;
+  close(): void;
+  ingestSubject(request: HostBytes, primary: HostBytes, resources: readonly HostBytes[]): HostBytes;
+  ingestMesh(request: HostBytes, mesh: HostBytes): HostBytes;
+  processRequest(request: HostBytes): HostBytes;
+  canonicalPlan(request: HostBytes): HostBytes;
+  evaluatePlan(plan: HostBytes): HostBytes;
+  evaluateClaim(request: HostBytes): HostClaimEvaluation;
+};
+/**
+ * Exact canonical bytes of one claim evaluated in one engine call: the bytes `canonicalPlan`,
+ * `canonicalize` of that plan's claim and `evaluatePlan` of that plan return. @public
+ */
+type HostClaimEvaluation = {
+  readonly canonicalPlan: HostBytes;
+  readonly canonicalClaim: HostBytes;
+  readonly canonicalResult: HostBytes;
+};
+/** Node lifecycle operations over opaque core control bytes. @public */
+type HostSubjectLifecycle = {
+  subjectHandle(request: HostBytes): HostBytes;
+  releaseSubject(request: HostBytes): HostBytes;
+};
+/** Explicit Node filesystem cache construction options. @public */
+type HostCacheOptions = {
+  readonly root: string;
+  readonly projectRoot: string;
+};
+/** Optional authenticated overlap-cache lifecycle. @public */
+type HostCacheLifecycle = {
+  flushCache(): HostBytes;
+  clearOverlapCache(): boolean;
+  cacheProducerIdentity(): HostBytes;
+};
+//#endregion
+export { HostBytes, HostCacheLifecycle, HostCacheOptions, HostClaimEvaluation, HostEngine, HostSubjectLifecycle, ProtocolError };

package/dist/host-types.mjs

@@ -0,0 +1 @@
+var e=class extends Error{code;constructor(e,t,n){super(t,n),this.name=`ProtocolError`,this.code=e}};const t=e=>typeof e==`object`&&!!e,n=n=>{if(n instanceof e)return n;if(t(n)&&typeof n.code==`string`&&typeof n.message==`string`)return new e(n.code,n.message,{cause:n});throw n},r=t=>{if(!(t instanceof Uint8Array))throw new e(`invalid-request`,`Host binding returned a non-byte value.`);return Uint8Array.from(t)},i=t=>{if(t.byteLength>=8){let e=new DataView(t.buffer,t.byteOffset,8),n=8+e.getUint32(0,!0),r=n+e.getUint32(4,!0);if(r<=t.byteLength)return{canonicalPlan:t.subarray(8,n),canonicalClaim:t.subarray(n,r),canonicalResult:t.subarray(r)}}throw new e(`invalid-request`,`Host binding returned a malformed claim evaluation.`)},a=e=>{try{return e()}catch(e){throw n(e)}},o=(e,t,n)=>{if(n===0)return;let r=t===`input`?`inputCopies`:`outputCopies`,i=t===`input`?`inputBytes`:`outputBytes`,a=e[i]+BigInt(n),o=18446744073709551615n;e[r]===o||a>o?e.exact=!1:(e[r]+=1n,e[i]=a)},s=(e,t)=>{let n=JSON.parse(new TextDecoder().decode(e));if(n.schema!==`geospec-engine-observations-v1`)throw Error(`Unsupported engine observation schema.`);n.exact=n.exact&&t.exact;for(let e of[`inputCopies`,`inputBytes`,`outputCopies`,`outputBytes`])n.copies[e]=(BigInt(n.copies[e])+t[e]).toString();return new TextEncoder().encode(JSON.stringify(n))};export{e as ProtocolError,s as appendHostObservationCopies,n as asProtocolError,a as callHost,o as observeHostCopy,r as toHostBytes,i as toHostClaimEvaluation};

package/dist/index.d.mts

@@ -0,0 +1,3 @@
+import { HostBytes, HostEngine, ProtocolError } from "./host-types.mjs";
+import { Engine, WasmInput, canonicalize, initialize } from "./wasm.mjs";
+export { Engine, type HostBytes, type HostEngine, ProtocolError, type WasmInput, canonicalize, initialize };

package/dist/index.mjs

@@ -0,0 +1 @@
+import{ProtocolError as e}from"./host-types.mjs";import{Engine as t,canonicalize as n,initialize as r}from"./wasm.mjs";export{t as Engine,e as ProtocolError,n as canonicalize,r as initialize};

package/dist/mixed-wasm-loader.d.mts

@@ -0,0 +1,16 @@
+import { HostBytes } from "./host-types.mjs";
+//#region src/mixed-wasm-loader.d.ts
+/** Input accepted by the compiled Emscripten module. @public */
+type WasmInput = ArrayBuffer | HostBytes | Response | URL | string | Promise<ArrayBuffer | HostBytes | Response | URL | string>;
+/** Ordered external binary resources paired with request metadata. @public */
+type WasmResources = readonly HostBytes[];
+/** Requested WASM product and caller-inclusive execution budget. @public */
+type WasmExecution = {
+  readonly variant: 'st';
+} | {
+  readonly variant: 'mt';
+  readonly permits: number;
+  readonly receipt: URL | string;
+};
+//#endregion
+export { WasmExecution, WasmInput, WasmResources };

package/dist/mixed-wasm-loader.mjs

@@ -0,0 +1,3 @@
+import{ProtocolError as e,appendHostObservationCopies as t,observeHostCopy as n}from"./host-types.mjs";const r=new TextDecoder(`utf-8`,{fatal:!0}),i=new TextEncoder().encode(`{"_tauNativeExactClusterCandidateV1":`);function a(e){return e.length>=i.length&&i.every((t,n)=>e[n]===t)}const o=t=>{if(!(t instanceof Uint8Array)||!(t.buffer instanceof ArrayBuffer))throw new e(`invalid-request`,`Host input must use an ordinary ArrayBuffer.`);return t},s=t=>{if(!Array.isArray(t))throw new e(`invalid-request`,`Host resources must be an array of ordinary ArrayBuffer views.`);return t.map(e=>o(e))},c=async e=>{let t=await e;if(t!==void 0)return t instanceof Uint8Array?{wasmBinary:o(t)}:t instanceof ArrayBuffer?{wasmBinary:new Uint8Array(t)}:t instanceof Response?{wasmBinary:new Uint8Array(await t.arrayBuffer())}:{locateFile:()=>t.toString()}};let l,u;const d=/* @__PURE__ */ new Map,f=t=>{if(t?.variant!==`mt`)return;if(!Number.isSafeInteger(t.permits)||t.permits<1||t.permits>4294967295)throw new e(`invalid-request`,`MT execution permits must be a positive wasm32 integer.`);let n=typeof process<`u`&&typeof process.versions.node==`string`;if(typeof SharedArrayBuffer>`u`||!n&&!globalThis.crossOriginIsolated)throw new e(`unsupported-capability`,`GeoSpec MT WASM requires a cross-origin-isolated browser worker.`);if(!t.receipt)throw new e(`unsupported-capability`,`No MT build receipt was supplied for mt-permits-${t.permits}.`);let r;try{r=new URL(t.receipt)}catch{throw new e(`invalid-request`,`MT build receipt must be an absolute URL.`)}if(n?r.protocol!==`file:`:r.origin!==location.origin)throw new e(`unsupported-capability`,`MT assets must use a local Node file or same-origin browser URL.`);return r},p=e=>typeof e==`object`&&!!e&&!Array.isArray(e),m=(t,n)=>{if(!p(t)||t.file!==n||typeof t.bytes!=`number`||!Number.isSafeInteger(t.bytes)||t.bytes<1||typeof t.sha256!=`string`||!/^[\da-f]{64}$/.test(t.sha256))throw new e(`unsupported-capability`,`MT receipt has no valid ${n} asset.`);return{file:n,bytes:t.bytes,sha256:t.sha256}},h=async t=>{if(t.protocol===`file:`){let{readFile:e}=await import(`node:fs/promises`);return Uint8Array.from(await e(t))}let n=await fetch(t);if(!n.ok)throw new e(`unsupported-capability`,`MT asset is unavailable: ${t.href}`);return new Uint8Array(await n.arrayBuffer())},g=async(t,n)=>{let{file:r}=n,i=await h(new URL(r,t)),a=Array.from(new Uint8Array(await crypto.subtle.digest(`SHA-256`,i)),e=>e.toString(16).padStart(2,`0`)).join(``);if(i.byteLength!==n.bytes||a!==n.sha256)throw new e(`unsupported-capability`,`MT asset does not match its build receipt: ${r}`);return i},_=async(t,n)=>{let i=JSON.parse(r.decode(await h(t)));if(!p(i)||i.schema!==`geospec-mixed-mt-assets-v1`||typeof i.permits!=`number`||!Number.isSafeInteger(i.permits)||i.permits<n)throw new e(`unsupported-capability`,`MT receipt does not describe mt-permits-${n}.`);let a=i.permits,o=m(i.glue,`geospec_engine_native.mjs`),s=m(i.wasm,`geospec_engine_native.wasm`),c=m(i.worker,`geospec_engine_native.mjs`),l=m(i.buildReceipt,`build-receipt.json`);if(c.bytes!==o.bytes||c.sha256!==o.sha256)throw new e(`unsupported-capability`,`MT receipt does not describe mt-permits-${n}.`);let u=new URL(`.`,t),d=await g(u,l),f=JSON.parse(r.decode(d));if(!p(f)||f.schema!==`geospec-mixed-build-receipt-mt-v1`||!p(f.mtSettings)||f.mtSettings.executionPermits!==a||!Array.isArray(f.artifacts)||![o,s].every(e=>f.artifacts.some(t=>p(t)&&typeof t.path==`string`&&t.path.endsWith(`/${e.file}`)&&t.bytes===e.bytes&&t.sha256===e.sha256)))throw new e(`unsupported-capability`,`MT assets do not match their qualified build receipt.`);await g(u,o);let _=await g(u,s),v=await import(
+/* @vite-ignore */
+new URL(o.file,u).href);if(typeof v.default!=`function`)throw new e(`unsupported-capability`,`MT module has no initializer.`);let y=await v.default({wasmBinary:_});if(typeof y._geospec_engine_native_engine_new_with_execution_permits!=`function`)throw new e(`unsupported-capability`,`MT module has no execution-permits constructor.`);if(!(y.wasmMemory?.buffer instanceof SharedArrayBuffer))throw new e(`unsupported-capability`,`MT module does not export wasmMemory; relink the MT product.`);return y},v=async(t,n)=>{let r=f(n);if(r!==void 0&&n?.variant===`mt`){if(t!==void 0)throw new e(`invalid-request`,`MT WASM bytes are selected by the build receipt.`);let i=`${n.permits}:${r.href}`,a=d.get(i);if(a===void 0){let e={promise:_(r,n.permits),module:void 0};a=e,d.set(i,e)}try{a.module=await a.promise}catch(e){throw d.get(i)===a&&d.delete(i),e}return}l??=(async()=>{let n=await import(`#mixed-wasm-binding`);if(typeof n.default!=`function`)throw new e(`invalid-request`,`Compiled GeoSpec WASM module has no initializer.`);return u=await n.default(await c(t)),u})();let i=l;try{await i}catch(e){throw l===i&&(l=void 0),e}},y=t=>{let n=f(t);if(n!==void 0&&t?.variant===`mt`){let r=d.get(`${t.permits}:${n.href}`);if(r?.module===void 0)throw new e(`invalid-request`,`Initialize the selected MT product before constructing an engine.`);return r.module}if(l===void 0)throw new e(`invalid-request`,`Call initialize() before using the GeoSpec WASM engine.`);if(u===void 0)throw new e(`invalid-request`,`Wait for initialize() before using the GeoSpec WASM engine.`);return u},b=e=>{let t=e.wasmMemory?.buffer;return t===void 0||t===e.HEAPU8.buffer?e.HEAPU8:new Uint8Array(t)},x=(e,t,n)=>{try{b(e).set(n,t)}catch(r){throw t!==0&&e._geospec_engine_native_input_free(t,n.byteLength),r}},S=(t,r,i)=>{let a=t._geospec_engine_native_input_alloc(r.byteLength);if(r.byteLength!==0&&a===0)throw new e(`limit-exceeded`,`Compiled GeoSpec WASM module could not register input bytes.`);return x(t,a,r),i&&n(i,`input`,r.byteLength),a},C=(t,r,i)=>{let a=t._geospec_engine_native_input_alloc(r.byteLength);if(r.byteLength!==0&&a===0)throw new e(`limit-exceeded`,`Compiled GeoSpec WASM module could not allocate binary input bytes.`);return x(t,a,r),i&&n(i,`input`,r.byteLength),a},w=(t,r,i)=>{let a=i.length(r)>>>0,o=i.pointer(r)>>>0;if(a===0)return/* @__PURE__ */ new Uint8Array;let s=b(t);if(o===0||o>s.byteLength||a>s.byteLength-o)throw new e(`invalid-request`,`Compiled GeoSpec WASM module returned an inconsistent byte range.`);let c=Uint8Array.from(s.subarray(o,o+a));return i.copies&&n(i.copies,`output`,a),c},T=(t,n,i)=>{if(n===0)throw new e(`invalid-request`,`Compiled GeoSpec WASM module returned no result.`);try{if(t._geospec_engine_native_result_is_error(n)!==0){let a=w(t,n,{copies:i,length:e=>t._geospec_engine_native_result_code_length(e),pointer:e=>t._geospec_engine_native_result_code_pointer(e)}),o=w(t,n,{copies:i,length:e=>t._geospec_engine_native_result_message_length(e),pointer:e=>t._geospec_engine_native_result_message_pointer(e)});throw new e(r.decode(a),r.decode(o))}return w(t,n,{copies:i,length:e=>t._geospec_engine_native_result_length(e),pointer:e=>t._geospec_engine_native_result_pointer(e)})}finally{t._geospec_engine_native_result_drop(n)}},E=(e,t,n)=>{let r=S(e,o(t.bytes),t.copies);try{return T(e,n(r,t.bytes.byteLength),t.copies)}finally{r!==0&&e._geospec_engine_native_input_free(r,t.bytes.byteLength)}};var D=class{#e;#t={exact:!0,inputCopies:0n,inputBytes:0n,outputCopies:0n,outputBytes:0n};#n;#r;constructor(t){if(this.#e=y(t),this.#r=t?.variant!==`mt`,this.#n=t?.variant===`mt`?this.#e._geospec_engine_native_engine_new_with_execution_permits?.(t.permits)??0:this.#e._geospec_engine_native_engine_new(),this.#n===0)throw new e(`invalid-request`,`Compiled GeoSpec WASM module could not create an engine.`)}close(){this.#n!==0&&(this.#e._geospec_engine_native_engine_drop(this.#n),this.#n=0)}ingestMesh(e,t){let n=o(t),r=this.engine();return E(this.#e,{bytes:e,copies:this.#t},(e,t)=>{let i=C(this.#e,n,this.#t),a=!1;try{return a=!0,this.#e._geospec_engine_native_ingest_mesh(r,e,t,i,n.byteLength)}finally{!a&&i!==0&&this.#e._geospec_engine_native_input_free(i,n.byteLength)}})}ingestSubject(t,n,r){let i=o(n),a=s(r),c=this.engine();return E(this.#e,{bytes:t,copies:this.#t},(t,n)=>{let r=[],o=0,s=0,l=!1;try{r.push({pointer:C(this.#e,i,this.#t),length:i.byteLength});for(let e of a)r.push({pointer:C(this.#e,e,this.#t),length:e.byteLength});if(s=a.length*8,o=this.#e._geospec_engine_native_input_alloc(s),s!==0&&o===0)throw new e(`limit-exceeded`,`Compiled GeoSpec WASM module could not allocate the resource table.`);let u=new DataView(b(this.#e).buffer);for(let t=1;t<r.length;t+=1){let n=r[t];if(n===void 0)throw new e(`invalid-request`,`Compiled GeoSpec WASM resource table is incomplete.`);let i=o+(t-1)*8;u.setUint32(i,n.pointer,!0),u.setUint32(i+4,n.length,!0)}let d=r[0];if(d===void 0)throw new e(`invalid-request`,`Compiled GeoSpec WASM primary input is missing.`);return l=!0,this.#e._geospec_engine_native_ingest_subject(c,t,n,d.pointer,d.length,o,a.length)}finally{if(o!==0&&this.#e._geospec_engine_native_input_free(o,s),!l)for(let e of r)e.pointer!==0&&this.#e._geospec_engine_native_input_free(e.pointer,e.length)}})}subjectHandle(e){return E(this.#e,{bytes:e,copies:this.#t},(e,t)=>this.#e._geospec_engine_native_subject_handle(this.engine(),e,t))}releaseSubject(e){return E(this.#e,{bytes:e,copies:this.#t},(e,t)=>this.#e._geospec_engine_native_release_subject(this.engine(),e,t))}processRequest(e){return E(this.#e,{bytes:e,copies:this.#t},(t,n)=>this.#r&&a(e)?this.#e._geospec_engine_native_exact_cluster_candidate_control(this.engine(),t,n):this.#e._geospec_engine_native_process_request(this.engine(),t,n))}canonicalPlan(e){return E(this.#e,{bytes:e,copies:this.#t},(e,t)=>this.#e._geospec_engine_native_canonical_plan(this.engine(),e,t))}evaluatePlan(e){return E(this.#e,{bytes:e,copies:this.#t},(e,t)=>this.#e._geospec_engine_native_evaluate_plan(this.engine(),e,t))}evaluateClaim(e){return E(this.#e,{bytes:e,copies:this.#t},(e,t)=>this.#e._geospec_engine_native_evaluate_claim(this.engine(),e,t))}observations(){let e=T(this.#e,this.#e._geospec_engine_native_observations(this.engine()));return t(e,this.#t)}engine(){if(this.#n===0)throw new e(`invalid-request`,`GeoSpec WASM engine is closed.`);return this.#n}};const O=e=>{let t=u??[...d.values()].find(e=>e.module!==void 0)?.module??y();return E(t,{bytes:e},(e,n)=>t._geospec_engine_native_canonicalize(e,n))};export{D as MixedWasmBinding,O as canonicalizeMixedWasm,v as initializeMixedWasm};