@gasm-compiler/core 0.3.2 → 0.5.0

package/LICENSE

@@ -0,0 +1,17 @@
+Copyright (c) 2025-present Gasm Compiler Authors
+
+All rights reserved.
+
+This software and associated documentation files (the "Software") are the
+proprietary property of the copyright holder(s). No permission is granted to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
+of the Software, except as expressly permitted in a separate written license
+agreement with the copyright holder(s).
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -4,7 +4,8 @@
 
 Transform WebAssembly binaries into WGSL (WebGPU Shading Language) compute shaders. Write your GPU kernels in any language that compiles to WebAssembly (C, C++, Rust, Go, AssemblyScript, or hand-written WAT), then run them on the GPU via WebGPU.
 
-Implements the [Gasm v0.1 specification](https://github.com/gasm-compiler/spec) — a GPU-executable subset of WebAssembly.
+Gasm v0.2 is the default through the Rust/Wasm compiler backend. Archived
+Gasm v0.1 behavior remains available through an explicit compatibility option.
 
 ---
 
@@ -49,6 +50,107 @@ const shaderModule = device.createShaderModule({ code: wgslCode });
 
 ## Usage
 
+### Specification Versions
+
+Gasm v0.2 is the default:
+
+```typescript
+const wgsl = compile(wasmBytes);
+```
+
+The default enables strict v0.2 validation and lowering. Existing consumers can
+keep the archived v0.1 compiler behavior explicitly:
+
+```typescript
+const wgsl = compile(wasmBytes, { specVersion: "0.1" });
+```
+
+Compile a v0.2 artifact and metadata sidecar through the Rust/Wasm compiler:
+
+```typescript
+import {
+  compileToArtifact,
+  validateGasmMetadataSchema,
+} from "@gasm-compiler/core";
+
+const result = compileToArtifact(wasmBytes);
+if (!result.ok) {
+  throw new Error(
+    `${result.diagnostics.errors[0]?.code}: ` +
+      `${result.diagnostics.errors[0]?.message}`,
+  );
+}
+
+const schema = validateGasmMetadataSchema(result.metadata);
+if (!schema.valid) throw new Error(schema.errors.join(", "));
+```
+
+Gasm v0.2 semantics are implemented only in `packages/core-rs` and distributed
+through its Wasm artifact. The TypeScript compiler implementation is retained
+at v0.1 for compatibility. Deno remains the runtime for the CLI and the live
+core/CLI test suites, including headless WebGPU execution.
+
+The CLI also defaults to v0.2:
+
+```bash
+gasm-compiler compile input.wasm \
+  --output output.wgsl \
+  --metadata output.gasm.json
+```
+
+Use `--spec-version 0.1` when compiling archived v0.1 inputs.
+
+#### Migrating from 0.3.x
+
+- Compilation now defaults to strict Gasm v0.2 validation.
+- Pass `{ specVersion: "0.1" }` to retain archived v0.1 behavior.
+- Gasm v0.2 extensions must be declared in the module's
+  `gasm.extensions` custom section.
+- Math extension scalar imports use explicit type suffixes such as
+  `sin_f32`. Legacy unsuffixed imports remain accepted for compatibility.
+
+Required extensions are declared by the module's `gasm.extensions` custom
+section. The CLI does not inject extensions, so validation reflects the exact
+module that will be distributed.
+
+### Integrator Workflow
+
+Playgrounds, compiler backends, and other embedders can prepare transient Wasm
+without modifying their producer toolchain:
+
+```typescript
+import {
+  compileWithRuntimeInfo,
+  prepareModule,
+} from "@gasm-compiler/core/browser";
+
+const prepared = prepareModule(wasmBytes, {
+  demotionPolicy: { f64: "allow", i64: "allow-lossy" },
+});
+if (prepared.errors.length > 0) {
+  throw new Error(prepared.errors[0].message);
+}
+
+const result = compileWithRuntimeInfo(prepared.wasmBytes, {
+  ...prepared.compileOptions,
+  mode: "strict",
+});
+if (!result.ok) throw new Error(result.diagnostics.errors[0].message);
+```
+
+`prepareModule()` defaults to integrator mode. It infers required extensions,
+merges a stable `gasm.extensions` section, and returns binding and mutable-global
+initialization data. Modules with undeclared mutable defined globals use the
+v0.1 private-global compatibility path to avoid shared-storage races.
+
+Use `{ mode: "strict" }` to analyze a distribution artifact without changing
+its bytes. Strict compilation through `compile()` and
+`compileWithDiagnostics()` remains unchanged and never injects extensions.
+
+`compileWithRuntimeInfo()` is also available from the main and browser entry
+points. It combines preparation, compilation, binding metadata, dispatch
+information, and mutable-global initialization into one result.
+
 ### Basic Compilation
 
 ```typescript
@@ -82,7 +184,10 @@ const wgslCode = compile(wasmBytes, {
 });
 ```
 
-When enabled, WebAssembly imports like `(import "gasm" "sin" (func ...))` compile to direct WGSL built-in calls (`sin(...)`) with zero overhead.
+When enabled, WebAssembly imports like
+`(import "gasm" "sin_f32" (func ...))` compile to direct WGSL built-in calls
+(`sin(...)`) with zero overhead. Unsuffixed scalar names such as `sin` remain
+accepted as legacy aliases.
 
 **Math Levels:**
 - **M0 (Core):** sin, cos, sqrt, abs, min, max, clamp, floor, ceil, etc.

package/dist/browser.d.ts

@@ -1,5 +1,5 @@
-import { C as CompileDiagnostics, D as DispatchInfo$1, a as CompileOptions } from './error_codes-D6RsiZ33.js';
-export { b as CompileError, h as ErrorCode, E as ErrorCodes, c as SPEC_VERSION_V01, d as SPEC_VERSION_V02, S as SpecVersion, e as isCompileError, g as isParseError, i as isV02Mode, f as parseWasmModule, r as resolveSpecVersion } from './error_codes-D6RsiZ33.js';
+import { C as CompileDiagnostics, D as DispatchInfo$1, G as GasmMetadata, a as GasmBinding, P as PreparedModule, b as CompileOptions, c as PrepareModuleOptions } from './error_codes-5zCZDwFZ.js';
+export { d as CompileError, h as DEFAULT_SPEC_VERSION, e as DemotionPolicy, f as Diagnostic, g as DiagnosticRecovery, o as ErrorCode, E as ErrorCodes, u as GasmMetadataEntryPoint, M as MutableGlobalsInit, x as PrepareMode, j as SPEC_VERSION_V01, k as SPEC_VERSION_V02, S as SpecVersion, w as buildBindingTable, s as buildGasmMetadata, l as isCompileError, n as isParseError, i as isV02Mode, m as parseWasmModule, p as prepareModule, r as resolveSpecVersion, v as validateGasmMetadataSchema } from './error_codes-5zCZDwFZ.js';
 export { BrowserGPUExecutor } from './browser-executor.js';
 export { BufferData, ExecuteOptions, ExecutionError, ExecutorConfig, IGPUExecutor, OutputBufferSpec, isExecutionError } from './executor.js';
 
@@ -67,6 +67,28 @@ type CompileWithDiagnosticsResult = {
     ok: false;
     diagnostics: CompileDiagnostics;
 };
+type CompileArtifactResult = {
+    ok: true;
+    wgsl: string;
+    metadata: GasmMetadata;
+    diagnostics: CompileDiagnostics;
+    dispatchInfo: DispatchInfo;
+} | {
+    ok: false;
+    diagnostics: CompileDiagnostics;
+};
+type CompileWithRuntimeInfoResult = {
+    ok: true;
+    wgsl: string;
+    diagnostics: CompileDiagnostics;
+    dispatchInfo: DispatchInfo;
+    bindings: GasmBinding[];
+    metadata: GasmMetadata;
+    mutableGlobalsInit?: PreparedModule["mutableGlobalsInit"];
+} | {
+    ok: false;
+    diagnostics: CompileDiagnostics;
+};
 interface BackendMismatchDetails {
     kind: "wgsl" | "ok_mismatch" | "rust_error" | "diagnostics";
     message: string;
@@ -88,6 +110,8 @@ interface BackendComparisonResult {
 }
 
 declare function compileWithDiagnostics(wasmBytes: Uint8Array, options?: CompileOptions): CompileWithDiagnosticsResult;
+declare function compileToArtifact(wasmBytes: Uint8Array, options?: CompileOptions): CompileArtifactResult;
+declare function compileWithRuntimeInfo(wasmBytes: Uint8Array, options?: PrepareModuleOptions): CompileWithRuntimeInfoResult;
 declare function compileWithDiagnosticsAsync(wasmBytes: Uint8Array, options?: CompileOptions, initOptions?: InitRustCompilerOptions): Promise<CompileWithDiagnosticsResult>;
 declare function compileWithBackendComparison(wasmBytes: Uint8Array, options?: CompileOptions, compareOptions?: {
     funcName?: string;
@@ -98,4 +122,4 @@ declare function compileWithBackendComparisonAsync(wasmBytes: Uint8Array, option
 declare function compile(wasmBytes: Uint8Array, options?: CompileOptions): string;
 declare function compileAsync(wasmBytes: Uint8Array, options?: CompileOptions, initOptions?: InitRustCompilerOptions): Promise<string>;
 
-export { type BackendComparisonResult, type BackendMismatchDetails, type BrowserCompilerBackend, CompileDiagnostics, CompileOptions, type CompileWithDiagnosticsResult, type DispatchInfo, type InitRustCompilerOptions, type WgslComparisonSummary, type WgslDiffOptions, compile, compileAsync, compileWithBackendComparison, compileWithBackendComparisonAsync, compileWithDiagnostics, compileWithDiagnosticsAsync, disassembleToWAT, exportWgslFunctionSnippet, formatUnifiedDiff, getBrowserCompilerBackend, initRustCompiler, isRustCompilerInitialized, normalizeWgslForComparison, preloadCompiler, setBrowserCompilerBackend, summarizeWgslComparison, waitForRustCompilerInit };
+export { type BackendComparisonResult, type BackendMismatchDetails, type BrowserCompilerBackend, type CompileArtifactResult, CompileDiagnostics, CompileOptions, type CompileWithDiagnosticsResult, type CompileWithRuntimeInfoResult, type DispatchInfo, GasmBinding, GasmMetadata, type InitRustCompilerOptions, PrepareModuleOptions, PreparedModule, type WgslComparisonSummary, type WgslDiffOptions, compile, compileAsync, compileToArtifact, compileWithBackendComparison, compileWithBackendComparisonAsync, compileWithDiagnostics, compileWithDiagnosticsAsync, compileWithRuntimeInfo, disassembleToWAT, exportWgslFunctionSnippet, formatUnifiedDiff, getBrowserCompilerBackend, initRustCompiler, isRustCompilerInitialized, normalizeWgslForComparison, preloadCompiler, setBrowserCompilerBackend, summarizeWgslComparison, waitForRustCompilerInit };