Skip to content

Ship the uorc client: CLI, library, wasm page, release and benchmark - #104

Merged
afflom merged 10 commits into
mainfrom
claude/project-thread-jl6avw
Nov 9, 2026
Merged

afflom merged 10 commits into
mainfrom
claude/project-thread-jl6avw

Conversation

@afflom

@afflom afflom commented Nov 8, 2026 •

Copy link
Copy Markdown
Member

Requested by Alex · project thread

What ships

  • client/src/Uorc/Client.lex.tex: the client's compress and decompress as LexLean production roots (rust-std, effects allocation/overflow/recursion).
  • client/src/Uorc/Codec/: the ulz codec in LexLean (LzEncode, LzDecode, Table) and Archive, which builds and reads UORC program archives whose program is the ulz decoder kernel. client/gen/ holds the generators; build.sh regenerates the sources byte-identically and check_graph.py runs the kernel graph through a Python mirror of the reference semantics.
  • generated/rust/uorc_{compress,decompress}: the certified Rust that lexlean production build exports from those roots (scripts/client-export.mjs).
  • crates/uorc: the library (compress, decompress, typed Error) and the uorc CLI (compress/decompress, --steps, --work, --stats).
  • crates/uorc-wasm and web/: a GitHub Pages site that runs the client in the browser, with worked examples and CLI/Rust/JS usage.
  • scripts/bench.mjs: a measure-only UC-PERF-01 benchmark against gzip, bzip2, xz, zstd and brotli.
  • .github/workflows/release.yml: on a v* tag it builds x86_64 and aarch64 binaries, the wasm bundle and a source tarball, runs the Canterbury benchmark, publishes the Release, and deploys Pages.

How compress chooses

An archive is a standard UORC archive sealed with UORC-SHA256-CHAIN-v1. compress writes the smaller of:

  • a kernel archive: the ulz decoder as a UORC program graph (2.6 KB) plus the LZ + range-coded payload as a sequence constant;
  • a raw archive: the input stored as is.

--steps N (default 0) additionally runs the engine search and keeps it if smaller. decompress takes a fast path when the archive rebuilds byte-for-byte from its payload (certified decode plus canonical re-encode check), and otherwise evaluates the program graph by the reference semantics.

Performance (1 MB samples: Rust sources and an ELF binary)

file uorc gzip -9 xz -9 compress decompress
Rust source 171,617 188,937 151,116 1.7 s 1.9 s
ELF binary 568,025 644,226 449,692 5.4 s 5.3 s

uorc beats gzip -9 and trails xz -9, and stored input decodes in milliseconds. On small files the kernel's fixed 2.6 KB dominates. The next throughput targets are the SHA-256 chain and the canonical re-encode check.

The export uses LexLean pinned at 4c41d39 (our patches, upstream as UOR-Foundation/lexlean#441 and #443). The pin moves to a LexLean release once they ship.

Tests

  • cargo test --release -p uorc: 8 passed (round trips, zero-budget archives, text takes the kernel archive, the kernel graph decodes by the reference semantics, fixture decode, budget and decode errors).
  • cargo clippy --workspace --all-targets -D warnings and cargo fmt --check: clean in CI.

After merge

  1. Enable Pages with Source set to GitHub Actions.
  2. Tag v0.1.0 to run the release.

🤖 Generated with Claude Code

https://claude.ai/code/session_013Asa3Nk2H9geAZ2GKFCNvM

claude and others added 10 commits November 8, 2026 11:08
…ges site, release and bench

Uorc.Client composes Search.Engine (whole-buffer compress under a step budget)
and the ArchiveTrial decode phases (decompress). scripts/client-export.mjs
stages the closure, marks it executable, works around LexLean 0.4.0 LLV7015
with a typed let wrap, and runs the certified production build into
generated/rust. Work in progress: the exported Rust is far slower than the
Lean-native build and overflows the stack on deep recursion.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_013Asa3Nk2H9geAZ2GKFCNvM
The client crates are re-exported with LexLean at 7da569d (rust-std keeps
datatype fields behind Rc), pinned in scripts/client-export.mjs until the
lowering is released. Compress runs 18x and decompress 5x faster than the
inline-record export, and the WebAssembly stack drops from 256 MiB to 64 MiB.
The generated crates leave the workspace members so the workspace fmt and
clippy gates do not re-lint or reformat LexLean's output.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_013Asa3Nk2H9geAZ2GKFCNvM
The authority graph links Client against a closure that is not marked
executable, so lexlean check refused Client's executable definitions
(LLT4001). The export now adds executability and the two production
annotations on its staged copy; the staged data form equals the one the
committed packages were exported from.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_013Asa3Nk2H9geAZ2GKFCNvM
The template trust root requires every checkout to fetch full history.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_013Asa3Nk2H9geAZ2GKFCNvM
…-place byte update #443)

The export pin moves to the branch that carries both LexLean patches; the
re-exported client gains the std runtime's Bytes::update and is otherwise
unchanged. The pin moves to a LexLean release once both ship.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_013Asa3Nk2H9geAZ2GKFCNvM
compress now writes a standard UORC program archive whose graph is the ulz
decoder kernel (45 blocks, ~3 KB on the wire) and whose payload is the ulz
encoder's output, or the raw archive when that is smaller. The program search
runs only when --steps asks for it. decompress recognises a kernel archive by
rebuilding it byte for byte, runs the certified LexLean decoder, and keeps the
result only if re-encoding reproduces the payload; every other archive takes the
reference path. The current reference client decodes kernel archives by the
graph semantics, and a test decodes one that way.

1 MB inputs: rust.rs 54,366 B (gzip -9 61,786, xz -9 46,924), elf.bin 202,696 B
(gzip 238,109, xz 183,444); compress 0.7-1.9 s, decompress 0.7-1.9 s.

The codec and the client live in client/src, outside the authority project,
because the codec's tables use the in-place byte update that only the pinned
LexLean has; client-export stages client/src over src. client/gen holds the
writing aids (regenerate with client/gen/build.sh; check_graph.py runs the
kernel graph by a Python mirror of the reference semantics).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_013Asa3Nk2H9geAZ2GKFCNvM
…ce path

decompress recognises a raw archive by rebuilding it from its body and
comparing bytes, so a stored input decodes in milliseconds.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_013Asa3Nk2H9geAZ2GKFCNvM
Scalars move to low store keys with per-width accessors, and the payload
is copied into the store once instead of being threaded through every
block. Archives shrink by about 390 bytes.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_013Asa3Nk2H9geAZ2GKFCNvM
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants