# Jacquard

> A small programming language designed for running, reviewing, simulating, and trusting programs written by ML models and reviewed by people, featuring algebraic effects, probabilistic programming, and content-addressed identity.

Jacquard is a FriendMachine research project — a small programming language built for a world where most code is written by machine-learning models and reviewed by humans. It ships as a compact `.jac` surface syntax, an OCaml checker and CPS interpreter, a C-emitting native AOT backend, a command-line tool, a Jacquard-written standard library, and a test framework called Warp. Version 0.1 is described by the project as a research prototype, not a production language.

## What It Is

Jacquard is a programming language in the capability-security and probabilistic-programming space, implemented in OCaml and licensed under Apache 2.0. Its core thesis is that when most code is written by machines, the language itself must answer "what can this touch, and how sure are we?" without requiring a human to read every line. It achieves this through four interlocking mechanisms: explicit effect signatures on every function arrow, swappable world handlers that let the same code run against real networks, scripted fakes, or probability models, exact discrete probabilistic inference as an ordinary library handler, and content-addressed structural identity that ignores formatting and comments.

## Core Language Mechanics

The kernel has exactly 27 forms, each represented as a `(head, meta, args)` triple. Key mechanisms include:

- **Type-and-effect rows**: Every function arrow carries the set of effects it may perform (e.g., `(text) ->{net} text`). The runtime rejects unhandled world effects unless explicitly granted via `--allow`.
- **Algebraic effects with deep, multi-shot handlers**: A handler can resume a computation zero, one, or many times, enabling exact Bayesian inference and exhaustive search as library code rather than runtime features.
- **Discrete probabilistic programming**: `sample` and `observe` are effect operations; each inference algorithm (exact enumeration, likelihood weighting) is a handler.
- **Content-addressed definitions**: Identity is a hash of canonical resolved structure with formatting, comments, and local renames erased. Pure tests rerun only when canonical code or dependency content changes.

## Tooling and CLI

The `jac` command-line tool exposes the full language surface:

- `jac run` — execute a `.jac` file with optional `--allow` grants
- `jac check` — type/effect check and print signatures or manifests
- `jac hash` — compute canonical content hash
- `jac fmt` / `jac diff` — format and structure-aware diff
- `jac infer enumerate` / `jac infer lw` — exact and approximate probabilistic inference
- `jac test` — run Warp tests with optional exhaustive mode and content-addressed cache
- `jac build` — native AOT compilation via C emission

The native backend emits C, specializes and caches units by content hash, and is differential-tested against the interpreter under both clang and gcc. Tail calls are O(1) stack on every toolchain.

## Update: Version 0.1 RC3

The current release is `jacquard-core-0.1-rc3`, installable without OCaml or opam via a single `curl` script. Pre-built binaries are published for Linux x86-64, macOS Intel, and macOS Apple Silicon. RC1 established the semantic boundary, pinned by 554 Alcotest/QCheck cases, 32 cram transcripts, and 21 documentation examples. RC2 repaired binary-demo packaging. RC3 adds an explicit runtime/output license exception and packages the native runtime. The successor distribution relicenses Jacquard under Apache License 2.0 with a runtime/output exception that allows user programs and compiled output to use any license their authors choose, including proprietary licenses. Language semantics pinned at RC1 are unchanged across these releases.

## Audience and Design Bet

Jacquard is explicitly designed for a regime where coding agents produce most source code and human reviewers need language-level guarantees rather than documentation or convention. The `docs/SKILL.md` file compresses the kernel, CLI, prelude, and Warp testing into a single file intended to load as a project skill for coding agents. The `AGENTS.md` file provides operating rules for future coding agents working on the codebase itself. Demos include agent-dream world simulation, preflight candidate plan scoring, and program repair as Bayesian inference — scenarios where a human or agent needs to reason about what a generated program can touch and how confident to be in its behavior.

## Current Limits

The project's own `docs/release/0.1/LIMITS.md` documents explicit non-goals: no VM/JIT, no concurrency, no membrane enforcement, no continuous distributions, no gradients, no typed staging, no language package management, no self-hosting, and no formal soundness proofs. World grants remain coarse. The `.jac` surface is an evolving v0 projection onto the permanent 27-form kernel.

## Features
- Algebraic effects with deep multi-shot handlers
- Type-and-effect rows on every function arrow
- Explicit capability grants via --allow flags
- Discrete probabilistic programming as library handlers
- Content-addressed structural identity and hashing
- Native AOT compilation via C emission
- Warp test framework with content-addressed cache
- Record/replay of world interactions
- Structure-aware canonical diff
- Exact enumeration and likelihood-weighting inference
- Swappable world handlers for testing and simulation
- Jacquard-written standard library (prelude)
- CLI tools: run, check, hash, fmt, diff, infer, test, build
- Pre-built binaries for Linux x86-64, macOS Intel, macOS Apple Silicon

## Integrations
OCaml (implementation language), Dune (build system), opam (package manager), clang / gcc (C toolchain for native AOT), GitHub Actions (CI/CD), asdf (tool version management), Alcotest / QCheck (test frameworks), Menhir (parser generator), ocamlformat (formatter)

## Platforms
WINDOWS, MACOS, LINUX, API, CLI

## Pricing
Open Source

## Version
0.1-rc3

## Links
- Website: https://github.com/jbwinters/jacquard-lang
- Documentation: https://github.com/jbwinters/jacquard-lang/blob/main/docs/README.md
- Repository: https://github.com/jbwinters/jacquard-lang
- EveryDev.ai: https://www.everydev.ai/tools/jacquard-lang