Jacquard
Jacquard is a FriendMachine research project for running, reviewing, simulating,
and trusting programs written by models and reviewed by people. Start with the
human-friendly introduction to Jacquard.
human-friendly introduction to Jacquard
Concretely, it is a small programming language with a compact .jac surface
syntax, an OCaml checker and CPS interpreter, a C-emitting native AOT backend
that currently compiles the kernel .jqd carrier, a command-line tool, a
Jacquard-written standard library, and a test framework called Warp. Version
0.1 works end to end but is a research prototype, not a production language;
docs/release/0.1/LIMITS.md is the honest boundary.
Install the 0.1 release candidate without OCaml or opam:
The expected output is 120. Linux x86-64, macOS Intel, and macOS Apple
Silicon binaries are published; development from source is documented below.
Then run one policy under concrete and probabilistic telemetry worlds, followed
by sampled and exhaustive Warp checks:
For Humans
Most languages tell you what a program computes. Jacquard also exposes which
effects it may perform, finite discrete uncertainty, and canonical program
identity. Tools can inspect all three because they live in the language rather
than only in comments, logs, or your memory of the codebase.
Things you can do here that most languages cannot offer:
Read one line and see the effects a function may perform. A signature like
(text) ->{net} text says the function may perform the net effect. The
Jacquard runtime rejects unhandled world effects unless their authority is
explicitly granted with --allow, including effects performed by dynamic
code. This is language-level enforcement in a research runtime, not a
substitute for an operating-system sandbox.
Run one program against many worlds. The same code can run against the real
network, a scripted fake, a recording of last week's traffic, or a
probability model of how servers usually behave. A handler is the piece
that answers a program's requests to the outside world; you swap the
handler, and the code never changes. This can replace much conventional
mocking at effect boundaries and makes "what would my agent do if the API
went down?" an ordinary test.
Enumerate exact probabilities for finite discrete models. A program can
sample weighted choices and record evidence, and enumeration lists every
reachable outcome with its exact probability. The repair demo below treats a
failing test as evidence and computes which patches remain possible and how
likely each is.
Rename and reformat without changing canonical identity. Jacquard hashes
canonical resolved structure rather than source bytes. Comments, formatting,
provenance, and ordinary local or term renames are erased; pure tests rerun
only when canonical code or dependency content changes. This is structural
identity, not a proof that arbitrary programs are behaviorally equivalent.
The bet behind all of this: when most code is written by machines, the humans
reviewing it need the language itself to answer "what can this touch, and how
sure are we" without reading every line.
For Agents
Read docs/SKILL.md first. It compresses the kernel, the CLI, the prelude,
Warp testing, and the known gotchas into one file, and it loads as a project
skill from docs/SKILL.md. Operating rules are in AGENTS.md. What
will save you time:
Behavior is pinned by evidence: cram transcripts under test/cli/, corpus
goldens, demo scripts, and docs/release/0.1/CLAIMS.md. If a pin fails,
treat it as information about your change, and never weaken a pin to make a
diff pass.
The kernel is 27 forms (docs/ast.md); .jac is a projection onto those
forms, and bootstrap .jqd remains permanently supported. Treat the shipped
surface boundary and its parked follow-ups as release evidence, not as a
frozen grammar; do not add out-of-scope features (AGENTS.md lists them).
The development gate is dune build @all && dune runtest && dune fmt
followed by a clean git diff --exit-code.
Core Ingredients
For readers who speak programming languages:
One uniform representation: every form is a (head, meta, args) triple, and
the kernel grammar has 27 forms. Quoted code is ordinary data.
Algebraic effects with deep, multi-shot handlers. A handler can resume a
computation zero, one, or many times, which is what makes exhaustive search
and exact inference ordinary library code.
Explicit capability grants. The runtime installs handlers for the outside
world only for effects you pass with --allow; there is no ambient
authority.
Type-and-effect rows. Every arrow carries the set of effects the function
may perform, so a program's inferred row is its authority manifest.
Discrete probabilistic programming as a library: sample and observe are
effect operations, and each inference algorithm is a handler.
Content-addressed definitions. Identity is a hash of canonical resolved
structure with non-identity metadata erased, so formatting, comments, and
ordinary local or term renames change nothing downstream.
Tooling that leans on the above: formatter, structure-aware differ, Warp
tests with a content-addressed cache, record/replay, and a reproducible
release evidence pack.
A native AOT path that emits C, specializes and caches units by content hash,
and is differential-tested against the interpreter under clang and gcc.
The prototype is complete against its original core plan and has since added
the public surface syntax, ringed standard library, Warp properties and cache,
native compilation, packaged binaries, and product-scale case studies. The RC1
semantic boundary is pinned by 554 Alcotest/QCheck cases, 32 cram transcripts,
21 documentation examples, native sanitizer/leak/fuzz lanes, and a fresh-clone
evidence workflow. RC2 repaired binary-demo packaging; RC3 adds an explicit
runtime/output license exception and packages the native runtime. The current
successor distribution relicenses Jacquard under Apache License 2.0 and keeps
that runtime/output permission as an explicit clarification. These licensing
and packaging changes do not change the language semantics pinned at RC1.
What It Looks Like
Here is one handler resuming one continuation twice. The block is copied
byte-for-byte to test/docs-doctest/fixtures/readme-multishot.jac and run by
the documentation test lane:
The handler ran the rest of the program once with true and once with
false, then collected both results. That ability to resume more than once is
why exact Bayesian inference is a library handler here rather than a runtime
feature. The repair demo builds on it: mutate a buggy program's quoted AST
into candidate patches, treat a failing test as an observation, and read off
the updated probabilities. Running candidate code is an authority, so the pure
step still runs (it counts eight candidate patches) and then the demo refuses
until you grant the rest:
Under the grant, one failing test leaves two surviving patches: the intended
fix at 0.75 and a patch that games the suite at 0.25. Adding one regression
test prunes the impostor, and the surviving fix prints as a one-line canonical
diff: - sub + add. See sh demos/tooling/repair.sh for the full transcript.
Install A Release Binary
Most users do not need OCaml or opam. Install the reviewed 0.1 RC binary with:
The installer detects your OS and CPU, downloads the matching archive and
SHA-256 checksum, refuses a checksum mismatch, and installs under ~/.local
by default. Make sure ~/.local/bin is on PATH, then run:
jac is the short alias for jacquard. Both commands set JACQUARD_PRELUDE
from the installed package, so ordinary runs do not need an environment variable:
Narrative demos ship with launchers that choose the installed binary and
prelude automatically. They do not require Dune:
Use these launchers rather than directly running a probabilistic model or a
multi-file entrypoint. The launcher selects infer where observation requires
it and assembles related files in isolated scratch space.
To install under a different user-owned prefix:
Set JACQUARD_INSTALL_VERSION to install a different release tag. Supported
binary targets are linux-x86_64, macos-x86_64, and macos-arm64; other
platforms currently require the development setup.
Release archives are attached to jacquard-core-* GitHub releases. Each
archive contains bin/jacquard, bin/jac, libexec/jacquard/jacquard,
share/jacquard/prelude, share/jacquard/demos, the native C runtime, and the
license, notice, exception, and trademark documents.
Development Quick Start
These commands assume a fresh clone and asdf available for installing opam.
If you already have opam 2.5.x, start at the local switch step. If opam
is already initialized on your machine, skip opam init.
The switch step compiles OCaml 5.1.1 from source, so expect the first setup to
take around ten minutes.
The final git diff --exit-code is part of the development contract: formatting
must leave the worktree clean unless you intentionally commit the formatting
diff.
Expected versions after setup:
opam 2.5.1 from .tool-versions
OCaml 5.1.1 from the repo-local _opam/ switch
dune, ocamlformat, alcotest, qcheck, digestif, menhir,
cmdliner, odoc, utop, and ocaml-lsp-server from jacquard.opam
In a new shell inside an existing checkout, run:
_opam/ is intentionally ignored. It is a local build artifact, not source.
Running Jacquard
During development, use the built binary through Dune:
Many direct CLI commands need the prelude. From the repository root:
The main commands are:
.jac is the user-facing surface carrier. Bootstrap .jqd remains fully
supported as the internal/debug syntax, quote notation, and kernel format of
record. run, check, hash, fmt, diff, infer, and test select
surface syntax by extension; native build, replay programs, the prelude, and
many internal fixtures continue to use .jqd.
Ordinary programs and demos need only a .jac source file. Do not hand-author
a .jqd twin unless a conformance test specifically needs to prove that both
carriers lower to the same kernel and hash. The paired files retained in the
corpus and selected demos are evidence fixtures, not an authoring requirement.
Native compilation
jacquard build currently accepts the kernel .jqd carrier and compiles a
program and its reachable declarations to a
standalone binary whose output is byte-identical to jacquard run —
stdout, stderr, and exit codes, pinned by a differential harness in CI
(scripts/native-diff.sh). The full effect language compiles, including
capturing and multi-shot handlers, and code values compile since task
73 — quotes, splices, and the structural code ops. eval alone stays
on the interpreter tier (E1102 policy: dynamically loaded code runs
where the authority model lives).
Requirements and knobs:
Release binaries discover their packaged prelude and C runtime
automatically. Source checkouts may set the two variables shown above.
A C toolchain: clang (any recent) or gcc. Tail calls are O(1) stack on
every toolchain: musttail on clang and gcc 15+, a trampoline below
them (the emitted C is identical either way).
The binary parses --allow EFFECT (console, clock, fs, dist, infer so
far), --seed N for the sampling grant, and refuses --infer-cache
and --dry-run (interpreter tooling) with pointed errors.
JACQUARD_STACK_MB sizes the program stack (default 1024): deep
non-tail recursion is real C recursion in this backend.
Compiled units cache under .jacquard-native/, keyed by content, so
an unchanged program relinks without recompiling.
Measured performance lives in docs/benchmarks.md — nine scenarios
with interpreter, native (both toolchains), Python, and hand-C
columns — with the claim boundaries in docs/native-compilation.md
(reproduce with scripts/native-bench.sh).
Demos
Start with these from the repo root after dune build @all. The same scripts
also work in an installed bundle without opam or Dune:
What they show:
case-studies/stormglass/: one checkout policy under simulated network and
clock laws, exact incident forecasts, and Warp proofs over all 27 worlds.
case-studies/release-risk/: one release policy under concrete and
probabilistic telemetry, plus a Warp safety proof over all 18 worlds.
basics/m1.sh: factorial, multi-shot choice, and gated eval.
inference/m3.sh: one model under exact enumeration and likelihood weighting; same
model hash, different inference handler.
inference/clarifying-question.sh: an agent computes whether asking the user a
question is worth the interruption (value of information).
worlds/agent-dream.sh: one policy under scripted and probabilistic world handlers.
worlds/preflight.sh: candidate agent plans scored under alternate worlds; the
live policy still needs a Net grant after the dreams pass.
inference/ambiguity-pipeline.sh: an extraction pipeline that keeps its uncertainty;
the user's click becomes an observe.
tooling/showcase-warp-tests.sh: Warp checks for the clarifying-question,
dream-mode, and ambiguity demos.
tooling/repair.sh: program repair as Bayesian inference; a bug report is an
observation over computed single-edit patches, and the most likely patch
prints as a one-line canonical-structure diff.
worlds/m4-hostile.sh: generated-looking code that reaches for net; signatures and
manifests expose the authority.
worlds/escrow/run.sh: product-shaped generated workflow with manifest, dry-run,
Warp tests, fault exploration, replay, canonical diff, and approval by hash.
Demo paths are canonical within the categorized directories; there are no
flat compatibility aliases. The full catalog is in demos/README.md.
All public demo outputs are pinned by cram tests (recorded command-line
transcripts that fail on any drift), especially test/cli/demos.t,
test/cli/hostile-demo.t, test/cli/escrow.t, test/cli/showcase.t, and
test/cli/repair.t, test/cli/preflight.t, plus test/cli/case-studies.t for
the larger applications.
Release Evidence
The release-candidate evidence pack lives in docs/release/0.1/.
To reproduce the release evidence from this checkout:
The script installs dependencies, builds, runs the full test suite, checks
formatting, runs public demos, runs gauntlet tests, records jacquard --version,
and writes generated evidence under .scratch/release/0.1/.
Key release docs:
docs/release/0.1/EVIDENCE.md: what was built and what passed
docs/release/0.1/CLAIMS.md: semantic claims mapped to tests and caveats
docs/release/0.1/REPRO.md: fresh-clone reproduction steps
docs/release/0.1/FREEZE.md: frozen version/hash/store/CLI surfaces
docs/release/0.1/GAUNTLET.md: adversarial tests present and omitted
docs/release/0.1/LIMITS.md: explicit non-goals and caveats
docs/release/0.1/DECISION.md: release-candidate decision memo
docs/release/0.1/RELEASE-NOTES.md: public RC contents and install command
Repository Map
.github/: CI, release evidence workflow, and PR template.
AGENTS.md: operating notes for future coding agents.
bin/: jacquard CLI entry point.
corpus/: conformance corpus and golden outputs.
demos/: runnable examples and product-shaped demos.
docs/: design docs, tutorial, CI/CD, Warp, stdlib, errors, release evidence.
prelude/: Jacquard standard library and effect declarations.
scripts/release/: reproducible release evidence script.
spec/: kernel AST and canonical serialization specs.
src/: OCaml implementation.
test/: Alcotest/QCheck suites plus cram CLI transcripts.
jacquard.opam, dune-project: package and build metadata.
Implementation Map
src/form.ml, src/meta.ml, src/span.ml: uniform triple and metadata.
src/reader.ml, src/printer.ml: bootstrap .jqd notation and formatter.
src/kernel.ml: validator and typed kernel AST.
src/resolve.ml: names to content-addressed references.
src/canon.ml, src/hash.ml: HASH_V0 canonical serialization and hashing.
src/store.ml: object store and mutable name index.
src/value.ml, src/eval.ml: CPS evaluator and multi-shot handlers.
src/types.ml, src/check.ml: type/effect inference, rows, manifests,
exhaustiveness.
src/prelude.ml: prelude loader, builtin wiring, and root grants.
src/infer_dist.ml: exact enumeration and likelihood weighting.
src/diff.ml: canonical-structure diff over stores.
src/warp.ml: Warp test discovery, running, cache, and properties.
Documentation Map
Read these in order if you are new:
docs/README.md: documentation index and suggested reading paths.
docs/tutorial.md: runnable user-facing examples.
demos/README.md: demo catalog and what each demo proves.
docs/ci-cd.md: GitHub checks and release evidence process.
docs/release/0.1/EVIDENCE.md: release-candidate evidence overview.
Deeper design references:
docs/whitepaper.tex: historical initial design thesis, motivation, risks,
and related work; its roadmap and implementation-status sections are
outdated.
docs/ast.md: kernel AST and metadata/hash contract.
spec/jacquard-kernel-ast-m0.md: kernel source-of-truth spec.
spec/serialization.md: canonical byte format.
docs/stdlib.md: prelude and ringed standard library.
docs/warp-testing.md: Warp testing model.
docs/errors.md: diagnostic catalog.
docs/development-plan.md: original implementation plan.
Development Workflow
Before opening a PR:
When adding valid corpus files, regenerate golden hashes:
When touching release-facing demos, claims, CI, or semantics, also run:
CI/CD
GitHub Actions has three principal workflows:
CI / Development gate: build, full tests, clean formatting, version smoke,
and release-doc presence on PRs, main, and release/**.
Release Evidence / Reproduce 0.1 evidence: release branches, jacquard-core-*
tags, and manual dispatch; runs scripts/release/reproduce-0.1.sh and uploads
transcripts.
Release Binaries: jacquard-core-* tags and manual dispatch; builds
Linux/macOS tarballs with jacquard, jac, the prelude, demos, and native
runtime sources.
See docs/ci-cd.md for branch protection recommendations.
License
Jacquard is licensed under the Apache License, Version 2.0. See
LICENSE and NOTICE.
Your programs remain yours. Jacquard claims no copyright in source merely
because it is written, checked, interpreted, or compiled with Jacquard. Native
executables include Jacquard runtime material, so the
runtime and generated-output exception explicitly
allows user programs and compiled output to use any license their authors
choose, including proprietary licenses. The exception also removes Apache
License notice obligations that would otherwise arise solely from embedded
Runtime Material in a compiled program. This is a statement of project
licensing intent, not legal advice.
runtime and generated-output exception
The Jacquard name and project identity are governed by
TRADEMARKS.md. The code license does not grant trademark
rights.
Current Limits
Jacquard core is a research prototype, not a production platform. The .jac
surface is implemented and supported but remains an evolving v0 projection
onto the permanent 27-form kernel. Native AOT compilation and C-toolchain
optimization ship; a VM/JIT, concurrency, membrane enforcement, continuous
distributions, gradients, typed staging, language package management,
self-hosting, and formal soundness proofs do not. World grants remain coarse.
See docs/release/0.1/LIMITS.md for the exact Core 0.1 semantic boundary.
Troubleshooting
opam: command not found: install opam with asdf using .tool-versions, or
install a compatible opam manually.
Dune cannot find packages: run eval "$(opam env)" in this shell, then
reinstall deps with opam install --deps-only . --with-test --with-dev-setup --with-doc -y.
jacquard cannot find names from the prelude: set JACQUARD_PRELUDE=$PWD/prelude or
run through Dune from the repo root.
Formatting changed files: run opam exec -- dune fmt, inspect the diff, and
commit the formatting changes if they are intended.
Release reproduction writes generated evidence under .scratch/release/0.1/
by default. Set JACQUARD_RELEASE_OUT to use another disposable output path.