Evaluation Package

Overview

Stability: contract-backed reference

Authority: The normative format lives in spec/jacqos/v1/evaluation-package.schema.json. Digest identity and equivalence rules live in spec/jacqos/v1/digests.md. This page summarizes the exported artifact and shows how to read it.

An evaluation package is the frozen runtime handoff for one evaluator. You export it when you need to move the same ontology IR, canonical mapper semantics, helper digests, and related metadata between environments.

jacqos export evaluation-package

What It Contains

Component	Description
Ontology IR	The intermediate representation of all .dh rules, relation declarations, and invariants
Mapper semantics	Canonical mapper exports (the structural contract, not the Rhai source)
Helper digests	Content-addressed hashes of all helper functions (Rhai and Wasm)
Prompt bundle digest	Hash of all prompt files used by LLM capabilities
Capability declarations	The declared effect capabilities from jacqos.toml
Metadata	App ID, app version, export timestamp, and the evaluator digest

The Evaluator Digest

The evaluator digest is the package’s primary semantic identity, as defined in the digest authority above:

evaluator_digest = hash(ontology IR, mapper semantics, helper digests)

Two evaluation packages with the same evaluator digest will produce identical derived state from the same observations.

What Changes the Digest

Change	Digest changes?
Modify a .dh rule	Yes
Add or remove a relation declaration	Yes
Change a mapper’s atom output	Yes
Refactor mapper code without changing atom output	No
Modify a helper function	Yes
Change a prompt file	No (prompt changes affect prompt_bundle_digest, not evaluator_digest)
Change jacqos.toml capabilities	No (capabilities are metadata, not semantics)

Why Prompts Don’t Change the Evaluator Digest

Prompts influence LLM behavior, but the evaluator derives facts from observations — including observations produced by LLM effects. The prompt affects what the LLM says, but the evaluator’s job is to derive facts from whatever the LLM actually said. Two different prompts that produce the same LLM response observations will produce the same derived facts.

The digest authority tracks prompt_bundle_digest separately so you can detect prompt changes without conflating them with semantic changes to derivation logic.

Package Digest

The package digest covers the entire evaluation package contents:

package_digest = hash(frozen evaluation package contents)

This is broader than the evaluator digest — it includes metadata, capability declarations, and the prompt bundle digest. Use it when you need to verify that two packages are identical in every respect, not just semantically equivalent.

Migration Packages

A migration package is the local-to-cloud handoff around an evaluation package. Use it when you need to move a local app and lineage into JacqOS Cloud or an enterprise-managed cloud while preserving replay identity.

jacqos export migration-package

The migration package references the evaluation package, the redacted observation export, app files, verification bundle, BlobRefs, and any redaction, retention, review, or effect-receipt manifests. Importers must recompute digests and reject missing blobs, unsupported versions, and semantic identity drift. A local -> cloud -> local round trip is valid only when the lineage_id, evaluator_digest, package_digest, mapper_output_digest values, observation head, and verification result are preserved.

Rollback is lineage selection, not mutation. If a migration fails, keep the imported evidence inspectable and select a previous committed activation or lineage head instead of editing observations.

Identity Model

JacqOS uses a small number of explicit, non-interchangeable identities:

Identity	What it names	Scope
evaluator_digest	One semantic evaluation configuration	Derivation logic
package_digest	One frozen evaluation package	Everything in the package
mapper_output_digest	Canonical mapper export for one observation	One mapper’s structural output
lineage_id	One observation history	Observation store

These are not interchangeable. The evaluator digest tells you whether two packages will produce the same facts. The package digest tells you whether two packages are byte-identical.

Using Evaluation Packages

Export

jacqos export evaluation-package
# => Wrote evaluation package to .jacqos/packages/eval-pkg-sha256-a1b2c3.tar

Verify Against a Package

Evaluation packages are the contract surface for CI pipelines:

1. Export a package from your development environment
2. Ship it to CI alongside your fixtures
3. Replay fixtures against the package
4. Verify that derived state matches expected world state

Shadow Evaluation

You can run two evaluator versions side-by-side on the same lineage:

1. Export packages from both versions
2. Replay the same observations through each
3. Compare the derived facts — differences highlight semantic changes

This is the mechanism behind the Studio Activity Compare lens (with full dual-pane render in V1.1) and shadow builds in production.

What It Does Not Contain

Excluded	Why
Observations	Packages are evaluator-side only — observations are a separate export
Credentials	Never included — credential_ref names environment variables
Derived facts	Facts are computed, not stored — replay produces them
Effect results	Effect observations belong to the observation export
Rhai source code	The canonical mapper export is the contract, not the source

Migration packages add references to observations, verification evidence, and object handles, but they do not change the evaluation package contract.

Secrets are verified absent from all exports during jacqos verify. See the redaction check for details.

Next Steps

• CLI Reference — jacqos export commands
• jacqos.toml Reference — configuring capabilities and resources
• Golden Fixtures — digest-backed behavior proof
• Observation-First Thinking — why observations and evaluation are separate