judgment-pack

Status: pre-1.0

Tagged binaries are official only when they appear on this repository's GitHub Releases page with checksums.txt. Development checkouts may temporarily embed unreleased JPS snapshots, but the release workflow rejects them.

judgment-pack is the vendor-neutral reference runtime for the Judgment Pack Specification (JPS). It is a reference implementation, not the only valid one: the normative specification, schemas, and conformance corpus are owned by the separate judgment-pack-spec repository, and an independent implementation is judged against the complete normative requirements of the conformance class it claims — not against this runtime. Results from the corpus published for the exact version it names are required evidence for such a claim and are not exhaustive evidence of it (§3.4.1).

The runtime validates documents. It does not fetch a source, authorize an action, or establish truth, organizational authority, safety, or operational fitness. It bundles two specification versions, 0.1.0-draft and 0.2.0-draft, and validates a document against the exact version that document declares; 0.1.0-draft defines carrier, structural, and semantic document conformance only, and 0.2.0-draft changes no part of the document format.

One shared evaluator applies the specification's §§7–8 resolution model per ADR-0007, and eight surfaces reach it: jpack experimental evaluate and evaluate-corpus, the project walk jpack packs test, the graph verbs jpack experimental graph evaluate and graph test, and the experimental_evaluate, experimental_test_packs and experimental_test_graphs MCP tools. The experimental namespace is a stability statement: such a surface may change or be removed without compatibility promise. It is not a statement about conformance. That evaluator implements the evaluator conformance class Core 0.2.0-draft adds — the §8.2 input preflight, the §8.3 portable disposition with its RFC 8785 byte agreement, the §8.4 error classes and their fixed precedence, and the §10 limits — per ADR-0010 and ADR-0011. Only a pack declaring specVersion 0.2.0-draft is evaluated: §11 makes the declared value exact and requires an unedited 0.1.0-draft pack to be re-declared — one edit, the specVersion string, and nothing else in the document — before an implementation claiming this draft evaluates it, so any other version is refused as pack-not-conformant in the preflight phase.

This runtime's conformance claim is stated, in full and only, in CONFORMANCE.md. JPS §3.4.1 fixes the entire form such a claim may take — the class, one exact specVersion, the corpus version, the results obtained, and in the claim's own words that every row of that corpus version passed — so this README states no part of it and neither does any other surface: a partial restatement would be the partial claim §3.4.1 forbids. Read that file for the claim, its version scope, its evidence, and everything it does not assert, which includes anything at all about a pack, its facts, or the wisdom of acting on a disposition (§3.5). jpack experimental evaluate-corpus runs the bundled evaluation corpus and reports its rows — the evidence §3.4.1 requires of a claim of this class, and explicitly not exhaustive evidence of one; see CONFORMANCE.md.

That command carries one further opt-in, --rfc0008-quantifiers, which is a draft-RFC prototype per ADR-0009: it admits the collection quantifiers exists, every, and uniform proposed by the specification's RFC 0008 (Draft). Those operators belong to no published JPS version. A pack using one is not valid under JPS 0.1.0-draft, spec validate rejects it, the evaluator without the flag refuses it, and every successful evaluation payload produced under the flag says so in band through a draftPrototype member — a refusal is an operational error and carries none. The flag is CLI only; the MCP tool does not expose it.

The command binary is jpack. The project, repository, and release archives keep the judgment-pack name; the executable they carry is jpack.

Implemented commands

jpack version
jpack spec validate <pack-or->
jpack spec test-conformance [suite]
jpack spec schema <spec-version>
jpack spec examples [name]
jpack packs list        (jpack.json project convention; ADR-0012, not part of the spec)
jpack packs validate [--id X]
jpack packs test [--id X]   (EXPERIMENTAL SURFACE; claim: CONFORMANCE.md)
jpack packs suggest [--id X] [--base ROW] [--write F|-] [--max N] [--include-hugs]   (candidate row INPUTS, never rows; ADR-0024)
jpack packs lock        (declare the current documents as the project's reviewed set; ADR-0019)
jpack packs verify      (check the project against that reviewed set)
jpack packs lint [--producers M]   (every consulted pointer has a producer; ADR-0022)
jpack packs schema
jpack mcp
jpack experimental evaluate <pack-or->   (EXPERIMENTAL SURFACE; claim: CONFORMANCE.md)
jpack experimental evaluate --pack-id X   (EXPERIMENTAL SURFACE; resolves one decision id through jpack.json)
jpack experimental evaluate <pack-or-> --rfc0008-quantifiers   (DRAFT-RFC PROTOTYPE; not an input the class defines)
jpack experimental evaluate-corpus   (EXPERIMENTAL SURFACE; corpus results, the evidence §3.4.1 requires)
jpack experimental graph list   (EXPERIMENTAL: the configured graphs, resolved; ADR-0029)
jpack experimental graph validate <graph-or->   (EXPERIMENTAL composition prototype; spec RFC 0002, Draft; ADR-0015)
jpack experimental graph evaluate <graph-or-> [--inputs <file-or->]   (EXPERIMENTAL SURFACE; claim: CONFORMANCE.md)
jpack experimental graph explain <graph-or->   (the evaluation plan; nothing is evaluated)
jpack experimental graph test <graph-or-> --rows <file-or->   (EXPERIMENTAL SURFACE; claim: CONFORMANCE.md)
jpack experimental graph schema

The pack argument and --pack-id are mutually exclusive: one pack, one source, and supplying both or neither is an invocation error rather than a precedence rule. --pack-id honors --config and JPACK_CONFIG like every other command that reads a configuration.

The namespace is jpack spec, not jpack jps. JPS remains the name of the specification and the prefix of its provisional diagnostic codes.

The mcp command serves the same offline operations to a Model Context Protocol client over stdio, so an agent can validate documents as a tool call; see docs/mcp-clients.md for per-client setup and docs/agent-testing.md for the agent-driven testing protocol.

Install a tagged release

Download the archive for your operating system and architecture from GitHub Releases. Each archive includes the jpack binary, README, the CONFORMANCE.md claim the source it was built from carries, Apache-2.0 license, attribution notice, and third-party notices.

Asset names follow this pattern:

judgment-pack_<version>_<os>_<arch>.tar.gz
judgment-pack_<version>_windows_<arch>.zip

For example, release v0.1.0 uses judgment-pack_0.1.0_linux_amd64.tar.gz. Linux and macOS users can extract an archive and install the binary into a user-owned directory already on PATH:

tar -xzf judgment-pack_0.1.0_linux_amd64.tar.gz
install -m 0755 jpack "$HOME/.local/bin/jpack"
jpack version

On Windows, expand the .zip, move jpack.exe into a directory on your user PATH, and run:

jpack version

Verify the archive before extracting it. On Linux:

grep ' judgment-pack_0.1.0_linux_amd64.tar.gz$' checksums.txt | sha256sum --check

On macOS:

grep ' judgment-pack_0.1.0_darwin_arm64.tar.gz$' checksums.txt | shasum -a 256 --check

On Windows PowerShell:

(Get-FileHash .\judgment-pack_0.1.0_windows_amd64.zip -Algorithm SHA256).Hash
Select-String -Path .\checksums.txt -Pattern ' judgment-pack_0.1.0_windows_amd64.zip$'

The two Windows hashes must match. Release archives also carry GitHub build-provenance attestations, which a current GitHub CLI can verify:

gh attestation verify judgment-pack_0.1.0_linux_amd64.tar.gz --repo Judgment-Pack/judgment-pack-runtime

Packages for Homebrew, Scoop, apt, and go install are not published yet. In particular, source installation with go install does not receive the release linker metadata, so use a release archive when you need an accurately reported runtime version.

Build and try it locally

Go 1.24 or newer is required to build from source: internal/fssecure binds every project file read to a directory handle through os.Root, which is a Go 1.24 standard-library type.

If an older WSL setup has persisted GO111MODULE=off, clear it once with go env -u GO111MODULE. The commands below explicitly enable module mode as a compatibility measure.

env GO111MODULE=on CGO_ENABLED=0 go build -trimpath -o ./bin/jpack ./cmd/jpack
./bin/jpack --help
./bin/jpack version

From a sibling checkout of judgment-pack-spec, validate a synthetic example:

./bin/jpack spec validate ../judgment-pack-spec/examples/minimal-expense-approval.json
./bin/jpack spec validate --format json ../judgment-pack-spec/examples/minimal-expense-approval.json

Standard input is accepted explicitly with -:

./bin/jpack spec validate --format json - < pack.json

Run a bundled document-conformance corpus — 0.1.0-draft by default, or an exact bundled version: