wasm-mcp 0.1.2 → 0.2.0

package/dist/mcp/instructions.js

@@ -11,8 +11,8 @@ specification (https://github.com/WebAssembly/spec). Every response
 is deterministic over data pinned to a specific upstream commit and
 baked into the package at build time.
 
-Unofficial, community-maintained — not affiliated with, endorsed by,
-or sponsored by the W3C WebAssembly Community Group or Working Group.
+Not affiliated with, endorsed by, or sponsored by the W3C WebAssembly
+Community Group or Working Group.
 
 Common workflow:
   1. \`spec_version\` — call first when you need to cite the spec or

package/dist/mcp/tool_meta.js

@@ -25,7 +25,7 @@ export const TOOLS = [
     {
         name: "instruction_get",
         title: "Get instruction",
-        description: "Fetch one WebAssembly instruction by mnemonic (`i32.add`, `br_if`) or binary opcode (`0x6a`, `0xfd 0x89 0x02`) as structured JSON: opcode bytes, category, introducing version, stack type signature, and validation/execution prose anchors + spec URLs. Provide `mnemonic` or `opcode` (mnemonic wins if both match).",
+        description: "Fetch one WebAssembly instruction by mnemonic (`i32.add`, `br_if`) or binary opcode (`0x6a`, `0xfd 0x89 0x02`) as structured JSON: opcode bytes, category, introducing version, stack type signature, validation/execution prose anchors + spec URLs, and `traps` — the runtime conditions under which it traps (each with the spec's canonical trap name; empty + `can_trap: false` for instructions that never trap). Provide `mnemonic` or `opcode` (mnemonic wins if both match).",
         inputSchema: instructionGetSchema,
         examples: instructionGetExamples,
         handler: (a) => instructionGet(a),
@@ -33,7 +33,7 @@ export const TOOLS = [
     {
         name: "instruction_list",
         title: "List instructions",
-        description: "Enumerate WebAssembly instructions with optional filters: `category` (control, numeric, parametric, variable, table, memory, ref, i31, struct, array, extern, vec), `introduced_in` (1.0 | 2.0 | 3.0), and `prefix` (mnemonic prefix like `i32.`). Returns lightweight rows sorted by opcode; follow up with instruction_get for full detail.",
+        description: "Enumerate WebAssembly instructions with optional filters: `category` (control, numeric, parametric, variable, table, memory, ref, i31, struct, array, extern, vec), `introduced_in` (1.0 | 2.0 | 3.0), `prefix` (mnemonic prefix like `i32.`), and `can_trap` (only trapping / only non-trapping instructions). Returns lightweight rows (incl. `can_trap`) sorted by opcode; follow up with instruction_get for full detail incl. trap conditions.",
         inputSchema: instructionListSchema,
         examples: instructionListExamples,
         handler: (a) => instructionList(a),

package/dist/mcp/tools/instruction_list.d.ts

@@ -24,6 +24,7 @@ export declare const instructionListSchema: {
         "3.0": "3.0";
     }>>;
     prefix: z.ZodOptional<z.ZodString>;
+    can_trap: z.ZodOptional<z.ZodBoolean>;
     version: z.ZodDefault<z.ZodEnum<{
         main: "main";
         latest: "latest";
@@ -33,6 +34,7 @@ export type InstructionListArgs = {
     category?: InstructionCategory;
     introduced_in?: (typeof WASM_VERSIONS)[number];
     prefix?: string;
+    can_trap?: boolean;
     version?: VersionValue;
 };
 export declare const instructionListExamples: ({
@@ -41,6 +43,7 @@ export declare const instructionListExamples: ({
         category: string;
         introduced_in?: undefined;
         prefix?: undefined;
+        can_trap?: undefined;
     };
     note: string;
 } | {
@@ -49,6 +52,7 @@ export declare const instructionListExamples: ({
         category: string;
         introduced_in: string;
         prefix?: undefined;
+        can_trap?: undefined;
     };
     note: string;
 } | {
@@ -57,6 +61,16 @@ export declare const instructionListExamples: ({
         prefix: string;
         category?: undefined;
         introduced_in?: undefined;
+        can_trap?: undefined;
+    };
+    note: string;
+} | {
+    q: string;
+    input: {
+        can_trap: boolean;
+        category?: undefined;
+        introduced_in?: undefined;
+        prefix?: undefined;
     };
     note: string;
 })[];

package/dist/mcp/tools/instruction_list.js

@@ -22,6 +22,10 @@ export const instructionListSchema = {
         .min(1)
         .optional()
         .describe("Filter to mnemonics starting with this prefix, e.g. `i32.` or `v128.`. Case-insensitive."),
+    can_trap: z
+        .boolean()
+        .optional()
+        .describe("Filter by trapping behavior: `true` keeps only instructions that can trap at runtime, `false` keeps only those that never trap. See instruction_get for the per-instruction trap conditions."),
     version: versionArg,
 };
 export const instructionListExamples = [
@@ -40,6 +44,11 @@ export const instructionListExamples = [
         input: { prefix: "i32." },
         note: "Prefix filter is the quickest way to scope to one type family.",
     },
+    {
+        q: "Which instructions can trap?",
+        input: { can_trap: true },
+        note: "can_trap filters to the finite trapping set; each row's can_trap mirrors instruction_get's traps.",
+    },
 ];
 export function instructionList(args) {
     const records = loadInstructions(args.version);
@@ -47,6 +56,7 @@ export function instructionList(args) {
         category: args.category,
         version: args.introduced_in,
         prefix: args.prefix,
+        can_trap: args.can_trap,
     });
     return { count: instructions.length, instructions };
 }

package/dist/parser/instructions.d.ts

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { type TrapCondition } from "./traps.js";
 export declare const INSTRUCTION_CATEGORIES: readonly ["control", "numeric", "parametric", "variable", "table", "memory", "ref", "i31", "struct", "array", "extern", "vec"];
 export type InstructionCategory = (typeof INSTRUCTION_CATEGORIES)[number];
 export declare const WASM_VERSIONS: readonly ["1.0", "2.0", "3.0"];
@@ -51,6 +52,20 @@ export interface InstructionRecord {
         validation: string;
         execution: string;
     };
+    /**
+     * Whether this instruction can trap at runtime. `true` iff `traps`
+     * is non-empty. A quick boolean for "does this trap?" without
+     * inspecting the conditions.
+     */
+    can_trap: boolean;
+    /**
+     * The runtime conditions under which this instruction traps, each
+     * with the spec's canonical trap name. Empty for instructions that
+     * never trap (e.g. `i32.add`). Derived at build time from the
+     * spec's operator partiality + trapping instruction families; see
+     * `src/parser/traps.ts`.
+     */
+    traps: TrapCondition[];
 }
 export declare const InstructionRecordSchema: z.ZodObject<{
     mnemonic: z.ZodString;
@@ -86,6 +101,11 @@ export declare const InstructionRecordSchema: z.ZodObject<{
         validation: z.ZodURL;
         execution: z.ZodURL;
     }, z.core.$strip>;
+    can_trap: z.ZodBoolean;
+    traps: z.ZodArray<z.ZodObject<{
+        condition: z.ZodString;
+        name: z.ZodString;
+    }, z.core.$strip>>;
 }, z.core.$strip>;
 export interface RawInstruction {
     version: number | null;

package/dist/parser/instructions.js

@@ -9,6 +9,7 @@
 // joins the two and emits a stable record shape that the runtime
 // tools query directly — no LaTeX in the surface area.
 import { z } from "zod";
+import { deriveTraps } from "./traps.js";
 export const INSTRUCTION_CATEGORIES = [
     "control",
     "numeric",
@@ -32,6 +33,8 @@ export const InstructionRecordSchema = z.object({
     signature: z.object({ params_raw: z.string(), results_raw: z.string() }),
     anchors: z.object({ validation: z.string(), execution: z.string() }),
     urls: z.object({ validation: z.url(), execution: z.url() }),
+    can_trap: z.boolean(),
+    traps: z.array(z.object({ condition: z.string(), name: z.string() })),
 });
 const SPEC_BASE = "https://webassembly.github.io/spec/core";
 /** Build a full anchor URL into the rendered spec. */
@@ -224,6 +227,7 @@ export function normalizeInstructions(dump) {
         // String(1.0) drops the trailing `.0`, so use toFixed(1) to get
         // the canonical `"1.0"`/`"2.0"`/`"3.0"` form.
         const version = raw.version.toFixed(1);
+        const traps = deriveTraps(mnemonic);
         records.push({
             mnemonic,
             opcodes,
@@ -235,6 +239,8 @@ export function normalizeInstructions(dump) {
                 validation: instructionUrl(raw.validation),
                 execution: instructionUrl(raw.execution),
             },
+            can_trap: traps.length > 0,
+            traps,
         });
     }
     return { records, skipped: report };

package/dist/parser/traps.d.ts

@@ -0,0 +1,12 @@
+/** One way an instruction can trap. */
+export interface TrapCondition {
+    /** Terse description of the runtime condition that triggers the trap. */
+    condition: string;
+    /** The spec's canonical trap name (matches `.wast` `assert_trap` text). */
+    name: string;
+}
+/**
+ * Derive the trap conditions for an instruction mnemonic. Returns an
+ * empty array for instructions that cannot trap. Pure and total.
+ */
+export declare function deriveTraps(mnemonic: string): TrapCondition[];

package/dist/parser/traps.js

@@ -0,0 +1,112 @@
+// Per-instruction trap conditions.
+//
+// WebAssembly's trapping behaviour is a finite, well-defined property
+// of a small set of instruction families. This module encodes that
+// set as a pure mnemonic → conditions mapping, applied at build time
+// to the pinned instruction list. No execution, no scraping — the
+// rules express the spec's operator partiality (which operators are
+// partial, and on what input) and the trapping instruction families
+// (memory/table accesses, indirect calls, null dereferences).
+//
+// Trap NAMES are the spec's canonical strings, verified against the
+// pinned spec's own conformance suite (`test/core/*.wast`
+// `assert_trap` messages): `integer divide by zero`, `integer
+// overflow`, `invalid conversion to integer`, `out of bounds memory
+// access`, `out of bounds table access`, `undefined element`,
+// `uninitialized element`, `indirect call type mismatch`,
+// `unreachable`, `null reference`.
+//
+// Scope note: array accessors and `ref.cast` also trap, but with
+// conditions whose canonical names are NOT present in the pinned core
+// test suite (e.g. out-of-bounds array access, cast failure). Rather
+// than ship partial or unverified trap data, they are intentionally
+// omitted here; structs (no out-of-bounds, null-deref only) and the
+// single-condition reference instructions are modelled in full.
+// Canonical conditions, named once so the mapping reads cleanly.
+const DIVIDE_BY_ZERO = { condition: "divisor is zero", name: "integer divide by zero" };
+const DIV_OVERFLOW = {
+    condition: "signed overflow (INT_MIN / -1)",
+    name: "integer overflow",
+};
+const TRUNC_INVALID = {
+    condition: "operand is NaN or an infinity",
+    name: "invalid conversion to integer",
+};
+const TRUNC_OVERFLOW = {
+    condition: "truncated value is outside the target integer range",
+    name: "integer overflow",
+};
+const MEM_OOB = {
+    condition: "effective address + access size is outside the memory bounds",
+    name: "out of bounds memory access",
+};
+const MEM_RANGE_OOB = {
+    condition: "source or destination range is outside the memory bounds",
+    name: "out of bounds memory access",
+};
+const TABLE_OOB = {
+    condition: "index is outside the table bounds",
+    name: "out of bounds table access",
+};
+const TABLE_RANGE_OOB = {
+    condition: "source or destination range is outside the table bounds",
+    name: "out of bounds table access",
+};
+const CALL_INDIRECT_UNDEF = {
+    condition: "table index is outside the table bounds",
+    name: "undefined element",
+};
+const CALL_INDIRECT_UNINIT = {
+    condition: "table element is a null reference",
+    name: "uninitialized element",
+};
+const CALL_INDIRECT_TYPE = {
+    condition: "runtime function type does not match the expected type",
+    name: "indirect call type mismatch",
+};
+const nullRef = (condition) => ({ condition, name: "null reference" });
+/**
+ * Derive the trap conditions for an instruction mnemonic. Returns an
+ * empty array for instructions that cannot trap. Pure and total.
+ */
+export function deriveTraps(mnemonic) {
+    const m = mnemonic;
+    // `unreachable` always traps.
+    if (m === "unreachable") {
+        return [{ condition: "always — executing this instruction unconditionally traps", name: "unreachable" }];
+    }
+    // Integer division / remainder (partial operators).
+    if (/^i(32|64)\.div_s$/.test(m))
+        return [DIVIDE_BY_ZERO, DIV_OVERFLOW];
+    if (/^i(32|64)\.div_u$/.test(m))
+        return [DIVIDE_BY_ZERO];
+    // rem_s does NOT overflow (INT_MIN % -1 is defined as 0).
+    if (/^i(32|64)\.rem_[su]$/.test(m))
+        return [DIVIDE_BY_ZERO];
+    // Non-saturating float→int truncation. `trunc_sat_*` saturate and
+    // never trap, so the `_sat_` form deliberately fails this pattern.
+    if (/^i(32|64)\.trunc_f(32|64)_[su]$/.test(m))
+        return [TRUNC_INVALID, TRUNC_OVERFLOW];
+    // Memory accesses: every load / store variant, including SIMD
+    // lane/splat loads (`v128.load32_zero`, `v128.store8_lane`, …).
+    if (/\.(load|store)/.test(m))
+        return [MEM_OOB];
+    if (/^memory\.(init|copy|fill)$/.test(m))
+        return [MEM_RANGE_OOB];
+    // Table accesses.
+    if (/^table\.(get|set)$/.test(m))
+        return [TABLE_OOB];
+    if (/^table\.(init|copy|fill)$/.test(m))
+        return [TABLE_RANGE_OOB];
+    // Indirect call: out-of-bounds index, null element, type mismatch.
+    if (m === "call_indirect")
+        return [CALL_INDIRECT_UNDEF, CALL_INDIRECT_UNINIT, CALL_INDIRECT_TYPE];
+    // Reference instructions with a single null-dereference trap.
+    if (m === "ref.as_non_null")
+        return [nullRef("operand is a null reference")];
+    if (m === "call_ref")
+        return [nullRef("the function reference operand is null")];
+    if (/^struct\.(get|get_s|get_u|set)$/.test(m))
+        return [nullRef("the struct reference operand is null")];
+    return [];
+}

package/dist/spec/instructions_query.d.ts

@@ -5,6 +5,8 @@ export interface InstructionSummary {
     opcodes: number[];
     category: InstructionCategory;
     version: string;
+    /** Whether this instruction can trap at runtime (see instruction_get for conditions). */
+    can_trap: boolean;
 }
 export declare function toSummary(r: InstructionRecord): InstructionSummary;
 /** Format a byte array as the conventional space-separated hex string,
@@ -29,6 +31,8 @@ export interface ListFilter {
     version?: string;
     /** Substring matched against the mnemonic prefix, case-insensitive. */
     prefix?: string;
+    /** When set, keep only instructions that can (true) / cannot (false) trap. */
+    can_trap?: boolean;
 }
 /** Enumerate instructions, optionally filtered, sorted by opcode. */
 export declare function listInstructions(records: InstructionRecord[], filter?: ListFilter): InstructionSummary[];

package/dist/spec/instructions_query.js

@@ -4,7 +4,13 @@
 // the Worker can bundle it directly. Callers pass in the already
 // loaded instruction records.
 export function toSummary(r) {
-    return { mnemonic: r.mnemonic, opcodes: r.opcodes, category: r.category, version: r.version };
+    return {
+        mnemonic: r.mnemonic,
+        opcodes: r.opcodes,
+        category: r.category,
+        version: r.version,
+        can_trap: r.can_trap,
+    };
 }
 /** Format a byte array as the conventional space-separated hex string,
  *  e.g. `[0xFD, 0x89, 0x02]` → `"0xfd 0x89 0x02"`. */
@@ -68,6 +74,8 @@ export function listInstructions(records, filter = {}) {
         const p = filter.prefix.toLowerCase();
         out = out.filter((r) => r.mnemonic.toLowerCase().startsWith(p));
     }
+    if (filter.can_trap !== undefined)
+        out = out.filter((r) => r.can_trap === filter.can_trap);
     return [...out]
         .sort((a, b) => compareOpcodes(a.opcodes, b.opcodes))
         .map(toSummary);

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "wasm-mcp",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "mcpName": "io.github.xyzzylabs/wasm-mcp",
   "private": false,
-  "description": "Unofficial MCP server for the WebAssembly core specification — SHA-pinned instructions, types, sections, and search. Not affiliated with the W3C WebAssembly CG.",
+  "description": "MCP server for the WebAssembly core specification — SHA-pinned instructions, types, sections, and search. Not affiliated with the W3C WebAssembly CG.",
   "type": "module",
   "bin": {
     "wasm-mcp": "dist/mcp/server.js"