ox 1.0.5 → 1.1.0

package/src/wasm/_test/Engine.test.ts

@@ -0,0 +1,62 @@
+import { Engine as CoreEngine, Hash } from 'ox'
+import { Engine } from 'ox/wasm'
+import { describe, expect, test } from 'vp/test'
+
+describe('create', () => {
+  test('behavior: does not install', async () => {
+    const engine = await Engine.create()
+    expect(Object.keys(engine)).toMatchInlineSnapshot(`
+      [
+        "Hash",
+      ]
+    `)
+    // The whole point of `create` over `load`: benches, differential tests and
+    // composition all need the implementation without touching global state.
+    expect(CoreEngine.get()).toMatchInlineSnapshot('{}')
+  })
+
+  test('behavior: installs for the duration of a call', async () => {
+    // `with` is the case that genuinely needs a value: there is nothing
+    // installed for `set` to merge into.
+    const wasm = await Engine.create()
+    const inside = CoreEngine.with(wasm, () => Hash.keccak256('0xdeadbeef'))
+    expect(inside).toEqual(Hash.keccak256('0xdeadbeef'))
+    expect(CoreEngine.get()).toMatchInlineSnapshot('{}')
+  })
+})
+
+describe('load', () => {
+  test('behavior: merges with a later set, rather than being replaced', async () => {
+    await Engine.load()
+    CoreEngine.set({ Mnemonic: { toSeed: () => new Uint8Array(64) } })
+    expect(Object.keys(CoreEngine.get()).sort()).toMatchInlineSnapshot(`
+      [
+        "Hash",
+        "Mnemonic",
+      ]
+    `)
+  })
+
+  test('behavior: installs, and returns what it installed', async () => {
+    const before = Hash.keccak256('0xdeadbeef')
+
+    const engine = await Engine.load()
+
+    expect(Object.keys(CoreEngine.get())).toEqual(Object.keys(engine))
+    // Installing changes which implementation runs, never the answer.
+    expect(Hash.keccak256('0xdeadbeef')).toEqual(before)
+  })
+
+  test('behavior: routes every slot it reports', async () => {
+    await Engine.load()
+    expect(Object.keys(CoreEngine.get().Hash ?? {}).sort())
+      .toMatchInlineSnapshot(`
+      [
+        "hmacSha256",
+        "keccak256",
+        "ripemd160",
+        "sha256",
+      ]
+    `)
+  })
+})

package/src/wasm/_test/Hash.browser.test.ts

@@ -0,0 +1,50 @@
+import { keccak_256 } from '@noble/hashes/sha3.js'
+import { describe, expect, test, vi } from 'vp/test'
+import * as Engine from '../../core/Engine.js'
+import * as Hash from '../../core/Hash.js'
+import * as WasmHash from '../Hash.js'
+
+describe('create', () => {
+  test('behavior: instantiates asynchronously', async () => {
+    // Chrome refuses to compile modules above a few kilobytes synchronously on
+    // the main thread, so `new WebAssembly.Module` must never be reached. A spy
+    // is the only way to assert that, since the artifact happens to be small
+    // enough today that a synchronous compile would succeed.
+    const Module = vi.spyOn(globalThis.WebAssembly, 'Module')
+    const Instance = vi.spyOn(globalThis.WebAssembly, 'Instance')
+    try {
+      const engine = await WasmHash.create()
+      expect(Module).not.toHaveBeenCalled()
+      expect(Instance).not.toHaveBeenCalled()
+
+      const input = new Uint8Array(32).fill(1)
+      expect(engine.Hash.keccak256(input)).toEqual(keccak_256(input))
+    } finally {
+      Module.mockRestore()
+      Instance.mockRestore()
+    }
+  })
+
+  test('behavior: grows memory in a real browser, then hashes a small input', async () => {
+    const engine = await WasmHash.create()
+
+    const large = new Uint8Array(3 * 1024 * 1024).fill(7)
+    expect(engine.Hash.keccak256(large)).toEqual(keccak_256(large))
+
+    // `memory.grow` detached the previous `ArrayBuffer`; a retained view would
+    // now read zero bytes.
+    const small = new Uint8Array(32).fill(1)
+    expect(engine.Hash.keccak256(small)).toEqual(keccak_256(small))
+  })
+
+  test('behavior: ox uses the WASM implementation once installed', async () => {
+    Engine.set(await WasmHash.create())
+    try {
+      expect(Hash.keccak256('0xdeadbeef')).toBe(
+        '0xd4fd4e189132273036449fc9e11198c739161b4c0116a9a2dccdfa1c492006f1',
+      )
+    } finally {
+      Engine.reset()
+    }
+  })
+})

package/src/wasm/_test/Hash.fuzz.ts

@@ -0,0 +1,188 @@
+import { fc, test } from '@fast-check/vitest'
+import { hmac } from '@noble/hashes/hmac.js'
+import { ripemd160 } from '@noble/hashes/legacy.js'
+import { sha256 } from '@noble/hashes/sha2.js'
+import { keccak_256 } from '@noble/hashes/sha3.js'
+import { Hash as WasmHash } from 'ox/wasm'
+import { beforeAll, describe, expect } from 'vp/test'
+import { numRuns } from '../../../test/fuzz/numRuns.js'
+
+let engine: WasmHash.create.ReturnType
+
+beforeAll(async () => {
+  engine = await WasmHash.create()
+})
+
+/**
+ * `@noble/hashes` is the oracle: it is audited and it is what ox ships by
+ * default, so any divergence here is a bug in the WASM implementation. Published
+ * vectors live in `Hash.vectors.test.ts` and cover the case where both
+ * implementations could be wrong together.
+ *
+ * The distribution is weighted toward the sizes where padding and block-boundary
+ * bugs hide -- empty input, exact multiples of the keccak256 rate (136) and the
+ * SHA-2 block (64), and the 56-byte threshold at which the length counter no
+ * longer fits in the final block.
+ */
+const arbitraryInput = fc.oneof(
+  { arbitrary: fc.uint8Array({ maxLength: 300, minLength: 0 }), weight: 6 },
+  {
+    arbitrary: fc
+      .constantFrom(0, 1, 55, 56, 63, 64, 65, 111, 112, 135, 136, 137, 272)
+      .chain((size) => fc.uint8Array({ maxLength: size, minLength: size })),
+    weight: 3,
+  },
+  {
+    arbitrary: fc.uint8Array({ maxLength: 4096, minLength: 1024 }),
+    weight: 1,
+  },
+)
+
+/**
+ * HMAC key lengths straddling the 64-byte block. At or under it the key is
+ * zero-padded; over it, it is hashed first -- a different code path that the
+ * message-shaped arbitrary above would only reach by chance.
+ */
+const arbitraryKey = fc.oneof(
+  {
+    arbitrary: fc
+      .constantFrom(0, 1, 32, 63, 64, 65, 96, 128, 129)
+      .chain((size) => fc.uint8Array({ maxLength: size, minLength: size })),
+    weight: 3,
+  },
+  { arbitrary: fc.uint8Array({ maxLength: 200, minLength: 0 }), weight: 1 },
+)
+
+const primitives = {
+  hmacSha256: {
+    reference: (input: Uint8Array, key: Uint8Array) => hmac(sha256, key, input),
+    wasm: (input: Uint8Array, key: Uint8Array) =>
+      engine.Hash.hmacSha256(key, input),
+  },
+  keccak256: {
+    reference: (input: Uint8Array) => keccak_256(input),
+    wasm: (input: Uint8Array) => engine.Hash.keccak256(input),
+  },
+  ripemd160: {
+    reference: (input: Uint8Array) => ripemd160(input),
+    wasm: (input: Uint8Array) => engine.Hash.ripemd160(input),
+  },
+  sha256: {
+    reference: (input: Uint8Array) => sha256(input),
+    wasm: (input: Uint8Array) => engine.Hash.sha256(input),
+  },
+} as const
+
+type Name = keyof typeof primitives
+
+describe('Hash', () => {
+  test.prop({ input: arbitraryInput }, { numRuns })(
+    'keccak256 ≡ @noble/hashes',
+    ({ input }) => {
+      expect(engine.Hash.keccak256(input)).toEqual(keccak_256(input))
+    },
+  )
+
+  test.prop({ input: arbitraryInput }, { numRuns })(
+    'sha256 ≡ @noble/hashes',
+    ({ input }) => {
+      expect(engine.Hash.sha256(input)).toEqual(sha256(input))
+    },
+  )
+
+  test.prop({ input: arbitraryInput }, { numRuns })(
+    'ripemd160 ≡ @noble/hashes',
+    ({ input }) => {
+      expect(engine.Hash.ripemd160(input)).toEqual(ripemd160(input))
+    },
+  )
+
+  test.prop({ input: arbitraryInput, key: arbitraryKey }, { numRuns })(
+    'hmacSha256 ≡ @noble/hashes',
+    ({ input, key }) => {
+      expect(engine.Hash.hmacSha256(key, input)).toEqual(
+        hmac(sha256, key, input),
+      )
+    },
+  )
+})
+
+describe('memory', () => {
+  test.prop(
+    {
+      operations: fc.array(
+        fc.record({
+          input: arbitraryInput,
+          key: arbitraryKey,
+          name: fc.constantFrom<Name>(
+            'hmacSha256',
+            'keccak256',
+            'ripemd160',
+            'sha256',
+          ),
+        }),
+        { maxLength: 24, minLength: 2 },
+      ),
+    },
+    { numRuns },
+  )('an arbitrary sequence of calls agrees at every step', ({ operations }) => {
+    // Every primitive shares one region of WASM linear memory, reusing it call
+    // after call. A mis-sized reservation, an off-by-one write, or a digest read
+    // from the wrong offset can leave earlier bytes behind and still produce a
+    // correct answer in isolation -- it only shows up when calls of differing
+    // sizes and kinds are interleaved. Comparing every step of a random sequence
+    // is what catches that; a fixed a/b/a pattern does not.
+    for (const { input, key, name } of operations) {
+      const primitive = primitives[name]
+      expect(
+        primitive.wasm(input, key),
+        `${name} with a ${input.length} byte input`,
+      ).toEqual(primitive.reference(input, key))
+    }
+  })
+
+  test.prop(
+    {
+      sizes: fc.array(fc.integer({ max: 20, min: 0 }), {
+        maxLength: 6,
+        minLength: 2,
+      }),
+    },
+    { numRuns: Math.min(numRuns, 20) },
+  )('repeated growth keeps results correct', ({ sizes }) => {
+    // Each size is a page count. Going up grows linear memory and detaches the
+    // previous `ArrayBuffer`; coming back down must not, since WASM memory never
+    // shrinks. Either way the view has to be re-derived, and a stale one reads
+    // as zeroes rather than throwing.
+    for (const pages of sizes) {
+      const input = new Uint8Array(pages * 65_536).fill(pages & 0xff)
+      expect(engine.Hash.keccak256(input), `${pages} pages`).toEqual(
+        keccak_256(input),
+      )
+    }
+  })
+
+  test.prop({ input: arbitraryInput }, { numRuns })(
+    'digests never alias WASM memory',
+    ({ input }) => {
+      // A digest returned as a view over linear memory would be silently
+      // rewritten by the next call. Hold one across a larger call and check it.
+      const digest = engine.Hash.keccak256(input)
+      const snapshot = digest.slice()
+      engine.Hash.keccak256(new Uint8Array(input.length + 1024).fill(0xaa))
+      expect(digest).toEqual(snapshot)
+    },
+  )
+
+  test.prop({ input: arbitraryInput }, { numRuns })(
+    'inputs are not mutated',
+    ({ input }) => {
+      const snapshot = input.slice()
+      engine.Hash.keccak256(input)
+      engine.Hash.sha256(input)
+      engine.Hash.ripemd160(input)
+      engine.Hash.hmacSha256(input, input)
+      expect(input).toEqual(snapshot)
+    },
+  )
+})

package/src/wasm/_test/Hash.test-d.ts

@@ -0,0 +1,28 @@
+import type { Engine } from 'ox'
+import { Hash as WasmHash } from 'ox/wasm'
+import { expectTypeOf, test } from 'vp/test'
+
+type Created = Awaited<ReturnType<typeof WasmHash.create>>
+
+test('every primitive is present, so callers need no assertion', () => {
+  expectTypeOf<Created['Hash']['keccak256']>().toEqualTypeOf<
+    (input: Uint8Array) => Uint8Array
+  >()
+  expectTypeOf<Created['Hash']['sha256']>().toEqualTypeOf<
+    (input: Uint8Array) => Uint8Array
+  >()
+  expectTypeOf<Created['Hash']['ripemd160']>().toEqualTypeOf<
+    (input: Uint8Array) => Uint8Array
+  >()
+  expectTypeOf<Created['Hash']['hmacSha256']>().toEqualTypeOf<
+    (key: Uint8Array, message: Uint8Array) => Uint8Array
+  >()
+})
+
+test('blake3 is absent, because the WASM module does not implement it', () => {
+  expectTypeOf<Created['Hash']>().not.toHaveProperty('blake3')
+})
+
+test('the result is still an engine, so `Engine.set` accepts it', () => {
+  expectTypeOf<Created>().toExtend<Engine.Engine>()
+})

package/src/wasm/_test/Hash.test.ts

@@ -0,0 +1,211 @@
+import { hmac } from '@noble/hashes/hmac.js'
+import { ripemd160 } from '@noble/hashes/legacy.js'
+import { sha256 } from '@noble/hashes/sha2.js'
+import { keccak_256 } from '@noble/hashes/sha3.js'
+import { Bytes, Engine, Hash } from 'ox'
+import { Hash as WasmHash } from 'ox/wasm'
+import { beforeAll, describe, expect, test } from 'vp/test'
+import { hmacSha256ScratchSize, wasmBase64 } from '../internal/hashes.wasm.js'
+import * as hash from '../internal/hash.js'
+import * as internal from '../internal/instantiate.js'
+
+let engine: WasmHash.create.ReturnType
+
+beforeAll(async () => {
+  engine = await WasmHash.create()
+})
+
+describe('create', () => {
+  test('default', async () => {
+    expect(Object.keys(await WasmHash.create())).toMatchInlineSnapshot(`
+      [
+        "Hash",
+      ]
+    `)
+    expect(Object.keys((await WasmHash.create()).Hash)).toMatchInlineSnapshot(`
+      [
+        "hmacSha256",
+        "keccak256",
+        "ripemd160",
+        "sha256",
+      ]
+    `)
+  })
+
+  test('behavior: hands every caller its own engine', async () => {
+    const [a, b] = await Promise.all([WasmHash.create(), WasmHash.create()])
+
+    // Deliberately not the same object. A shared slot lets one caller's
+    // customisation for composition leak into what a later `create` -- or
+    // `Engine.load` -- installs.
+    expect(a).not.toBe(b)
+    expect(a.Hash).not.toBe(b.Hash)
+
+    a.Hash.keccak256 = () => new Uint8Array(32).fill(9)
+    const c = await WasmHash.create()
+    expect(c.Hash.keccak256(Bytes.from('0xdeadbeef'))).toEqual(
+      b.Hash.keccak256(Bytes.from('0xdeadbeef')),
+    )
+  })
+})
+
+// Sizes chosen around the block boundaries where padding bugs live: keccak256's
+// rate is 136 bytes, sha256 and ripemd160 use 64-byte blocks and need a second
+// block once the remainder reaches 56.
+const sizes = [
+  0, 1, 2, 31, 32, 55, 56, 63, 64, 65, 71, 72, 111, 135, 136, 137, 199, 200,
+  271, 272, 1000,
+]
+
+function input(size: number) {
+  return new Uint8Array(size).map((_, index) => (index * 37 + 11) & 0xff)
+}
+
+describe('Hash', () => {
+  test.each(sizes)('keccak256 matches the default at %i bytes', (size) => {
+    expect(engine.Hash.keccak256(input(size))).toEqual(keccak_256(input(size)))
+  })
+
+  test.each(sizes)('sha256 matches the default at %i bytes', (size) => {
+    expect(engine.Hash.sha256(input(size))).toEqual(sha256(input(size)))
+  })
+
+  test.each(sizes)('ripemd160 matches the default at %i bytes', (size) => {
+    expect(engine.Hash.ripemd160(input(size))).toEqual(ripemd160(input(size)))
+  })
+
+  test.each([0, 1, 32, 63, 64, 65, 200])(
+    'hmacSha256 matches the default with a %i byte key',
+    (size) => {
+      const key = new Uint8Array(size).fill(0xa5)
+      const message = input(100)
+      expect(engine.Hash.hmacSha256(key, message)).toEqual(
+        hmac(sha256, key, message),
+      )
+    },
+  )
+
+  test('behavior: known vectors', () => {
+    expect(Bytes.toHex(engine.Hash.keccak256(new Uint8Array(0)))).toBe(
+      '0xc5d2460186f7233c927e7db2dcc703c0e500b653ca82273b7bfad8045d85a470',
+    )
+    expect(Bytes.toHex(engine.Hash.sha256(new Uint8Array(0)))).toBe(
+      '0xe3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855',
+    )
+    expect(Bytes.toHex(engine.Hash.ripemd160(new Uint8Array(0)))).toBe(
+      '0x9c1185a5c5e9fc54612808977ee8f548b2258d31',
+    )
+  })
+
+  test('behavior: grows memory past 64 MiB, then still hashes small inputs', () => {
+    // The input itself is exactly 64 MiB, so the heap base and digest force
+    // memory past that boundary. Growing detaches the previous `ArrayBuffer`; a
+    // retained view would silently read zero bytes in the assertion below.
+    const large = new Uint8Array(64 * 1024 * 1024).fill(7)
+    expect(engine.Hash.sha256(large)).toEqual(sha256(large))
+
+    const small = input(32)
+    expect(engine.Hash.sha256(small)).toEqual(sha256(small))
+  })
+
+  test('behavior: hmacSha256 clears its complete memory region', async () => {
+    const module = await internal.instantiate<hash.Exports>(wasmBase64)
+    const key = input(120)
+    const message = input(17)
+    const out = 32
+    const messagePtr = module.heapBase
+    const keyPtr = messagePtr + message.length
+    const outPtr = keyPtr + key.length
+    const scratchPtr = Math.ceil((outPtr + out) / 4) * 4
+    const end = scratchPtr + hmacSha256ScratchSize
+    const stack = module.view().slice(0, module.heapBase)
+
+    expect(hash.hmacSha256(module, key, message)).toEqual(
+      hmac(sha256, key, message),
+    )
+
+    expect(module.view().slice(0, module.heapBase)).toEqual(stack)
+    expect(module.view().slice(messagePtr, end)).toEqual(
+      new Uint8Array(end - messagePtr),
+    )
+  })
+
+  test('behavior: hmacSha256 clears its complete region after a trap', async () => {
+    const module = await internal.instantiate<hash.Exports>(wasmBase64)
+    const key = input(120)
+    const message = input(17)
+    const out = 32
+    const messagePtr = module.heapBase
+    const keyPtr = messagePtr + message.length
+    const validOutPtr = keyPtr + key.length
+    const scratchPtr = Math.ceil((validOutPtr + out) / 4) * 4
+    const end = scratchPtr + hmacSha256ScratchSize
+    const stack = module.view().slice(0, module.heapBase)
+    // Preserve the production boundary while making the real export trap only
+    // after it has populated the scratch buffer.
+    const exports = {
+      hmac_sha256(
+        keyPtr: number,
+        keyLength: number,
+        messagePtr: number,
+        messageLength: number,
+        _outPtr: number,
+        scratchPtr: number,
+      ) {
+        module.exports.hmac_sha256(
+          keyPtr,
+          keyLength,
+          messagePtr,
+          messageLength,
+          module.view().length - 16,
+          scratchPtr,
+        )
+      },
+      zero: (ptr: number, length: number) => module.exports.zero(ptr, length),
+    }
+    const trappingModule = { ...module, exports }
+
+    expect(() => hash.hmacSha256(trappingModule, key, message)).toThrow(
+      WebAssembly.RuntimeError,
+    )
+    expect(module.view().slice(0, module.heapBase)).toEqual(stack)
+    expect(module.view().slice(messagePtr, end)).toEqual(
+      new Uint8Array(end - messagePtr),
+    )
+
+    module.exports.zero(module.view().length - 16, 16)
+    expect(hash.hmacSha256(module, key, message)).toEqual(
+      hmac(sha256, key, message),
+    )
+  })
+
+  test('behavior: consecutive calls do not corrupt each other', () => {
+    const a = input(200)
+    const b = input(7)
+    expect(engine.Hash.keccak256(a)).toEqual(keccak_256(a))
+    expect(engine.Hash.keccak256(b)).toEqual(keccak_256(b))
+    expect(engine.Hash.keccak256(a)).toEqual(keccak_256(a))
+  })
+
+  test('behavior: results do not alias WASM memory', () => {
+    const first = engine.Hash.keccak256(input(32))
+    const snapshot = first.slice()
+    engine.Hash.keccak256(input(64))
+    expect(first).toEqual(snapshot)
+  })
+})
+
+describe('Engine.set', () => {
+  test('behavior: ox uses the WASM implementation once installed', () => {
+    Engine.set(engine)
+    expect(Hash.keccak256('0xdeadbeef')).toBe(
+      '0xd4fd4e189132273036449fc9e11198c739161b4c0116a9a2dccdfa1c492006f1',
+    )
+    expect(Hash.sha256('0xdeadbeef')).toBe(
+      '0x5f78c33274e43fa9de5659265c1d917e25c03722dcb0b8d27db8d5feaa813953',
+    )
+    expect(Hash.ripemd160('0xdeadbeef')).toBe(
+      '0x226821c2f5423e11fe9af68bd285c249db2e4b5a',
+    )
+  })
+})

package/src/wasm/_test/Hash.vectors.test.ts

@@ -0,0 +1,117 @@
+import { Hash as WasmHash } from 'ox/wasm'
+import { beforeAll, describe, expect, test } from 'vp/test'
+import * as vectors from '../../../test/vectors/hashes/index.js'
+import { wasmBase64 } from '../internal/hashes.wasm.js'
+import { instantiate } from '../internal/instantiate.js'
+
+/**
+ * Published vectors against the WASM implementations.
+ *
+ * The differential tests in `Hash.test.ts` and `Hash.fuzz.ts` prove the WASM
+ * agrees with `@noble/hashes`. These prove it agrees with the specifications, so
+ * a fault the two implementations happened to share would still be caught.
+ * See `test/vectors/hashes/README.md`.
+ */
+
+let engine: WasmHash.create.ReturnType
+
+beforeAll(async () => {
+  engine = await WasmHash.create()
+})
+
+describe('sha256', () => {
+  test(`matches ${vectors.sha256.length} NIST CAVP vectors`, () => {
+    for (const { digest, message } of vectors.sha256)
+      expect(engine.Hash.sha256(message)).toEqual(digest)
+  })
+})
+
+describe('hmacSha256', () => {
+  test(`matches ${vectors.hmacSha256.length} RFC 4231 vectors`, () => {
+    // Two of these use 131-byte keys, which is the only coverage of the
+    // longer-than-a-block path where the key is hashed before padding.
+    for (const { digest, key, message } of vectors.hmacSha256)
+      expect(engine.Hash.hmacSha256(key, message)).toEqual(digest)
+  })
+})
+
+describe('ripemd160', () => {
+  test(`matches ${vectors.ripemd160.length} reference vectors`, () => {
+    for (const { digest, message } of vectors.ripemd160)
+      expect(engine.Hash.ripemd160(message)).toEqual(digest)
+  })
+
+  test('matches the million-`a` reference vector', () => {
+    const { digest, message } = vectors.ripemd160MillionA
+    expect(engine.Hash.ripemd160(message)).toEqual(digest)
+  })
+})
+
+describe('keccak256', () => {
+  test(`matches ${vectors.keccak256.length} OpenSSL vectors`, () => {
+    for (const { digest, message } of vectors.keccak256)
+      expect(engine.Hash.keccak256(message)).toEqual(digest)
+  })
+})
+
+describe('keccak_f1600', () => {
+  type Exports = { keccak_f1600(state: number): void }
+
+  /** Writes 25 lanes as little-endian 64-bit words, permutes, and reads back. */
+  async function permute(lanes: readonly bigint[]) {
+    // A separate instance, because this export is not part of the engine and so
+    // is deliberately not reachable through `WasmHash.load`.
+    const module = await instantiate<Exports>(wasmBase64)
+    module.reserve(200)
+    const view = module.view()
+    for (let lane = 0; lane < 25; lane++) {
+      let value = lanes[lane]!
+      for (let byte = 0; byte < 8; byte++) {
+        view[module.heapBase + lane * 8 + byte] = Number(value & 0xffn)
+        value >>= 8n
+      }
+    }
+
+    module.exports.keccak_f1600(module.heapBase)
+
+    const after = module.view()
+    const result: bigint[] = []
+    for (let lane = 0; lane < 25; lane++) {
+      let value = 0n
+      for (let byte = 7; byte >= 0; byte--)
+        value =
+          (value << 8n) | BigInt(after[module.heapBase + lane * 8 + byte]!)
+      result.push(value)
+    }
+    return result
+  }
+
+  test('matches the Keccak team‘s reference examples', async () => {
+    for (const example of vectors.keccakPermutation.examples)
+      expect(await permute(example.input)).toEqual(example.output)
+  })
+
+  test('reference examples chain, so the second is not a restatement', () => {
+    // XKCP's second example feeds the first one's output back in. Asserting the
+    // link means a parser that silently read the same block twice would fail
+    // here rather than quietly halving the coverage above.
+    const [first, second] = vectors.keccakPermutation.examples
+    expect(second!.input).toEqual(first!.output)
+    expect(second!.output).not.toEqual(first!.output)
+  })
+
+  test('the parsed fixture is internally consistent', () => {
+    // Checks the fixture, not the implementation. Each `rounds[n]` is the state
+    // after round `n`'s iota step, and nothing exported reaches a single round,
+    // so per-round agreement is not observable from here -- the permutation
+    // itself is covered above, end to end against `input`/`output`. What this
+    // catches is a parser that mis-read the file and quietly weakened that.
+    const { examples, rhoOffsets, roundConstants } = vectors.keccakPermutation
+    expect(roundConstants).toHaveLength(24)
+    expect(rhoOffsets).toHaveLength(25)
+    for (const example of examples) {
+      expect(example.rounds).toHaveLength(24)
+      expect(example.rounds.at(-1)).toEqual(example.output)
+    }
+  })
+})

package/src/wasm/_test/Runtime.test.ts

@@ -0,0 +1,21 @@
+import { readFileSync } from 'node:fs'
+import { expect, test } from 'vp/test'
+import { instantiate } from '../internal/instantiate.js'
+import { wasmBase64 } from './runtime.wasm.js'
+
+test('freestanding runtime preserves memmove and realloc semantics', async () => {
+  const module = await instantiate<{ run(): number }>(wasmBase64)
+  expect(module.exports.run()).toBe(0)
+})
+
+test('memmove compares flat-memory offsets rather than C object pointers', () => {
+  const source = readFileSync(
+    new URL('../../../wasm/src/ox_rt.c', import.meta.url),
+    'utf8',
+  )
+  const body = source.match(/void \*memmove\([\s\S]*?\n}\n\nvoid \*memset/)?.[0]
+
+  expect(body).toBeDefined()
+  expect(body).toContain('if ((size_t)d < (size_t)s)')
+  expect(body).not.toMatch(/if\s*\(\s*d\s*<\s*s\s*\)/)
+})