01 - Vision Brief

One-sentence description

clj-zig is an experiment/demo/proof-of-concept for a Clojure-first, data-oriented interface to ordinary Clojure functions backed by real Zig implementations.

What clj-zig is

clj-zig is, for now:

• a proof-of-concept Clojure library;
• a REPL-native Zig function bridge;
• a data model for Clojure-to-Zig boundary contracts;
• a way to expose real Zig from Clojure without making users manage shared libraries directly;
• a foundation for exploring Clojure-side builders that compose Zig boundary types as data.

What clj-zig is not

clj-zig is not:

• a new language;
• a Zig-like DSL;
• a Clojure implementation;
• a Zig implementation;
• a JVM replacement;
• a generic object bridge;
• a serializer for arbitrary Clojure data;
• a bidirectional runtime system in the proof of concept.

Name

The name is clj-zig.

It is descriptive rather than clever: clj for Clojure, zig for the Zig that backs each function. The library defines ordinary Clojure functions whose bodies are real Zig, so the name says what it does.

Target users

Primary users:

• Clojure programmers who need selected native-speed functions;
• Clojure library authors building high-performance kernels;
• data-oriented Clojure programmers who want native contracts as data;
• Zig programmers who want a Clojure-hosted REPL workflow;
• tool builders who want to generate native kernels from Clojure data.

Core thesis

Clojure and Zig have complementary strengths:

Clojure: data, macros, homoiconicity, REPL, composition, host orchestration
Zig: explicit types, layout, allocators, comptime, C interop, performance

clj-zig's experimental bet is that the seam between them should be a small, explicit, Clojure-data boundary contract.

Product stance

The experience should not be:

(compile-zig ...)
(load-shared-library ...)
(lookup-symbol ...)
(invoke-native ...)

The experience should be:

(defnz add
  [x :i64
   y :i64
   :ret :i64]
  "return x + y;")

(add 1 2)

The user should think:

I defined a Clojure function whose implementation happens to be Zig.

Not:

I manually compiled and loaded a native library.

Proof-of-concept success criteria

clj-zig succeeds if:

1. defnz feels like a natural relative of defn.
2. Zig types are explicit where the native boundary needs them.
3. The signature is ordinary Clojure data.
4. Zig remains real Zig, not a weakened DSL.
5. Re-evaluating forms at the REPL feels like redefining functions.
6. Generated Zig and normalized specs are inspectable.
7. The system is decomposed enough for users to build higher-level Clojure abstractions on top.