NATIVE_BINDING.md

# SKC-LISP Native Binding: NASM Assembly Validators

Fast-path optimization for critical Lisp runtime operations: mutation validation gate (8-point check) and cryptographic verification (Blake3 + Ed25519).

## Architecture

```

┌─────────────────────────────────────────────────────────────────┐

│ MCP Server (ClojureScript) → Clojure tools                       │

├─────────────────────────────────────────────────────────────────┤

│ native.cljs (ClojureScript API)                                 │

│ - load-native-library!()  → loads .node binding                 │

│ - validate-mutation!()    → calls mutation_validate_gate ASM    │

│ - verify-blake3!()        → calls blake3_verify ASM             │

│ - verify-ed25519!()       → calls ed25519_verify ASM            │

├─────────────────────────────────────────────────────────────────┤

│ binding.cc (Node.js C++ addon via V8)                            │

│ - LoadAsmLibrary()        → dlopen/dlsym ASM library            │

│ - ValidateMutation()      → wrap mutation_validate_gate call    │

│ - VerifyBlake3()          → wrap blake3_verify call             │

│ - VerifyEd25519()         → wrap ed25519_verify call            │

├─────────────────────────────────────────────────────────────────┤

│ libskclisp_asm.so (x64 NASM shared object)                      │

│ - mutation-validator.asm  → 8-point gate + helper functions    │

│ - digest-verifier.asm     → Blake3/Ed25519 stubs                │

└─────────────────────────────────────────────────────────────────┘

```

## Compilation

### Build from scratch:

```bash

npm run build:native

```

This compiles:
1. `native/mutation-validator.asm` → `native/build/Release/mutation-validator.o`
2. `native/digest-verifier.asm` → `native/build/Release/digest-verifier.o`
3. Link into `native/build/Release/libskclisp_asm.so`
4. Compile C++ binding `native/binding.cc` → `native/build/Release/skclisp_native.node`

### Prerequisites:

- NASM (x86-64 assembler): `apt install nasm` (Linux) or `brew install nasm` (macOS)
- Node.js development headers (included with Node.js)
- node-gyp: `npm install -g node-gyp`
- C++ compiler (g++ or clang)

## Runtime Startup

When the MCP server starts:

```cljs

(native/load-native-library! "./native/build/Release/skclisp_native.node")

```

This:
1. Calls `LoadAsmLibrary` in the C++ binding
2. Opens the NASM shared object with `dlopen`
3. Loads function pointers: `mutation_validate_gate`, `blake3_verify`, `ed25519_verify`
4. Returns true if all pointers loaded successfully

## MCP Tools

Three new tools registered with the server:

### 1. `validate_mutation` — 8-point mutation gate



**Input schema:**

```json

{

  "mutation-id": number,

  "generation-before": number,

  "generation-after": number,

  "actor": number,

  "target": number,

  "operation": number (optional),

  "old-digest": string (optional),

  "new-digest": string (optional)

}

```



**Validation checks:**

1. Target exists in object store (or allocation requested)

2. Old digest matches stored value

3. New digest matches replacement

4. Replacement is well-formed (passes semantic checks)

5. All references in replacement are valid

6. Code in replacement is valid

7. Invariants are preserved

8. Generation counter advances (strictly monotonic)



**Return:**

```json

{

  "passes-gate": true/false,

  "error-code": 0-8 (failure check) | 255 (pass),

  "details": "human-readable message"

}

```



### 2. `verify_blake3` — Digest verification

**Input schema:**
```json

{

  "payload": string (base64 or hex),

  "expected-digest": string (base64 or hex)

}

```

**Return:**
```json

{

  "digest-valid": true/false,

  "error-code": 0 (match) | 1 (mismatch) | 2 (invalid),

  "details": "human-readable message"

}

```

### 3. `verify_ed25519` — Signature verification



**Input schema:**

```json

{

  "message": string,

  "signature": string (base64 or hex),

  "public-key": string (base64 or hex)

}

```



**Return:**

```json

{

  "signature-valid": true/false,

  "error-code": 0 (valid) | 1 (invalid) | 2 (invalid_input),
  "details": "human-readable message"
}
```



## Assembly Details



### Mutation Validator (`mutation-validator.asm`)



Entry point: `mutation_validate_gate(mutation_event*, object_store*, validation_result*)`



System V AMD64 ABI calling convention:

- `rdi` = pointer to mutation_event struct (64 bytes)

- `rsi` = pointer to object_store

- `rdx` = pointer to validation_result (2-byte output)



**mutation_event struct:**

```
[0]   mutation_id       (u64)

[8]   generation_before (u64)
[16]  generation_after  (u64)

[24]  actor             (u64)

[32]  target            (u64)

[40]  operation         (u32)

[44]  reserved          (u32)

[48]  old_digest (ptr)  (u64)
[56]  new_digest (ptr)  (u64)

```



**validation_result:**

```

[0]   passes_gate (u8, 1=pass, 0=fail)
[1]   error_code  (u8, 0-8 for check failures, 255=pass)

```



Returns: 1 (all pass), 0 (failure code in result buffer)



### Digest Verifier (`digest-verifier.asm`)



**blake3_verify(payload*, payload_length, expected_digest*, result*)**

- Currently a stub (validates input alignment, assumes match)

- Requires linking against libblake3.a for production



**ed25519_verify(message*, message_length, signature*, public_key*, result*)**

- Currently a stub (validates input, assumes valid)

- Requires linking against libsodium for production



Both stubs set result[0] = 1 (valid) and result[1] = 0 (no error) on valid input.



## Development Workflow



1. **Edit assembly:** Modify `native/*.asm` files

2. **Rebuild:** `npm run build:native`

3. **Test:** `npm test` (runs integration tests)

4. **Run MCP:** `npm run watch` + test with Claude Code



## Linking External Libraries



For production Blake3/Ed25519:



1. Install libraries:

   ```bash

   apt install libblake3-dev libsodium-dev

   ```



2. Update `native/binding.gyp` to link:

   ```json

   "ldflags": ["-ldl", "-lblake3", "-lsodium"]

   ```



3. Replace stub implementations in `digest-verifier.asm` with actual crypto calls



4. Rebuild: `npm run build:native`



## Performance Notes



- **Mutation validation:** O(8) checks, ~100ns per check (CPU bound)

- **Blake3 verification:** O(payload_length) with SIMD acceleration when linked
- **Ed25519 verification:** O(1) point multiplication, ~5-10µs per signature
- Native binding eliminates JS→WASM boundary (~1-2µs per call)

## Troubleshooting

### `Failed to load ASM symbols`
- Ensure `libskclisp_asm.so` exists at `native/build/Release/`
- Run `npm run build:native` to recompile

### `NASM: command not found`
- Install: `apt install nasm` or `brew install nasm`

### `node-gyp ERR! not ok`
- Ensure Node.js dev headers: `apt install nodejs-dev` or via Node.js installer
- Clear cache: `npm run build:native -- --clean`

### Segfault on library load
- Check that the `.so` was built for the correct architecture (x86-64)
- Verify dlopen can find the library (check LD_LIBRARY_PATH)

## References

- **System V AMD64 ABI:** https://en.wikipedia.org/wiki/X86_calling_conventions#System_V_AMD64_ABI

- **Node.js C++ addons:** https://nodejs.org/api/addons.html

- **NASM manual:** https://www.nasm.us/doc/

- **Blake3:** https://github.com/BLAKE3-team/BLAKE3

- **Libsodium:** https://doc.libsodium.org/