V1 Stability and Upgrade Promises

Overview

This page is the contract. If you are about to build a production system on JacqOS V1, this is what you can rely on staying stable for the V1 lifecycle, what JacqOS reserves the right to change in a V1.x point release, and what will only change at the V2 boundary.

JacqOS uses three stability tags from the hardening policy: contract (frozen — only a major-version boundary moves it), pinned (stable in V1 by default; explicit, announced changes only), and exploratory (subject to change in any release). Every documented field in jacqos.toml carries one of these tags. This page lifts those tags up to platform-wide guarantees.

The page is organized around six questions:

1. What is stable in V1?
2. What can change in V1.x without breaking your app?
3. What is shipped but explicitly not stable in V1?
4. What requires a V2 boundary?
5. How will JacqOS migrate you across that boundary?
6. How do app_version (your app) and jacqos_version (the binary) interact?

1. What Is Stable in V1

The following surfaces are contract or pinned. They will not break in any V1.x release. If a V1.x release changes one of these in a way that affects existing apps, that is a regression — file an issue.

.dh grammar

The Datalog subset documented in the .dh Language Reference is the V1 grammar. Specifically:

• The full EBNF grammar in §Grammar of that page is contract.
• The reserved domain prefixes atom(), intent., invariant, helper., candidate., and proposal. are contract.
• The supported aggregate operators (count, sum, min, max) and their shape constraints are contract.
• The validator’s load-time rejections — recursive aggregates, unstratified negation, ambient I/O, dynamic rule loading, and the relay-boundary check for requires_relay-marked atoms — are contract.

A rule that loads under V1.0.0 will continue to load under every V1.x release.

jacqos.toml schema

The 8 top-level keys in jacqos.toml (app_id, app_version, paths, capabilities, resources, studio, retention, mapper_budgets) are stable per their per-key tags. Tables marked contract (notably [capabilities] and [resources]) cannot change shape; tables marked pinned ([paths], [studio], [retention], [mapper_budgets]) accept additive evolution but no breaking change. Strict deserialization remains in effect: unknown keys at the top level and inside nested contract tables are still load errors in V1.x.

CLI command surface

The published CLI commands documented in the CLI Reference are stable. Specifically:

• jacqos scaffold, dev, serve, observe, activation show, activation promote, run, replay, verify, stats, gc, reconcile inspect, reconcile resolve, contradiction list, contradiction preview, contradiction resolve, and the export family (observations, facts, evaluation-package, verification-bundle, graph-bundle, benchmark-report).
• Every flag and positional argument documented as published behavior on those commands.
• Top-level --version and --help.

Output kind matters too: commands documented to emit JSON or JSONL on stdout will continue to do so. The published transport for the inspection API (versioned under tools/jacqos-cli/protocols/inspection-v1/) is pinned.

Effect capabilities

The built-in effect capabilities are contract:

• http.fetch
• llm.complete
• blob.put / blob.get
• timer.schedule
• log.dev

Their semantics, declaration shape in [capabilities], and [capabilities.intents] binding format will not change in V1.x. New capabilities may be added (see §2), but none of these built-ins will be removed or renamed.

Provider record/replay modes for http.fetch and llm.complete are also contract: record permits provider dispatch and persists the capture, while replay requires a matching capture and refuses live dispatch.

Verification bundle format

The bundle format authority lives at spec/jacqos/v1/verification-bundle.schema.json. The version: "jacqos_verify_v1" envelope is contract. A V1.0 bundle will deserialize, validate, and continue to compare cleanly under every V1.x release. The fields documented on the Verification Bundle page — evaluator_digest, prompt_bundle_digest, summary, checks, redaction_findings, fixtures, and the per-fixture provenance_graph — are stable.

Rhai mapper API

The mapper and helper host surfaces documented in the Rhai Mapper API are stable: the map_observation(obs) entrypoint, the obs field set, the atom(...) host function, the canonical mapper export shape (mapper_output_digest), the resource budget keys, and the standard library exposed inside the sandbox. Two mappers that produce the same canonical export today will produce the same digest under every V1.x release.

Diagnostic codes

The EXYYZZ diagnostic scheme catalogued under proposals_plans/ground-truth/diagnostics.md is the V1 stable-error-code surface. Once a code reaches pinned status (the V1.0 inventory of 47 codes spanning E0001–E2501), it has a single, unchanging meaning. CI scripts and IDE integrations can match on these codes and rely on the message template’s identity for the lifetime of V1.

2. What Can Change in V1.x (Additive Only)

V1.x point releases may add new behavior. They will not break existing apps that load and verify cleanly today. The following categories of change are expressly allowed:

• New CLI subcommands and flags. Any new flag is opt-in. Existing flags retain their meaning, default values, and exit codes.
• New .dh keywords and built-in relations. New keywords are reserved in their own namespace (e.g. a future aggregate qualifier) and never conflict with relation names that load today. Existing .dh files continue to parse and validate without modification.
• New diagnostic codes. New codes extend the EXYYZZ ranges. Existing codes do not change meaning, severity, or template.
• New Studio surfaces. The V1.1 visual rule graph, dual-pane Compare rendering, and inline negation-witness display all ship as additions. Existing left-nav surfaces (Home, Observations, Facts, Provenance, Execution, Graphs, Replay, Export, Compare, Contradictions, Reconcile, Timeline) and their published controls do not regress.
• New effect capabilities. Any new capability is declared opt-in inside [capabilities]. Apps that do not declare it are unaffected.
• New jacqos verify rubric rules. New checks are introduced behind a versioned verify profile when they would change pass/fail outcomes for existing apps; backwards-compatible checks may roll out in the default profile but always with a release-note callout.
• New [resources] providers and modes. New provider names and provider_mode variants extend the allowed set. Existing values continue to validate.

If you find a V1.x change that breaks an app conformant with the V1.0 contract above, that is a regression.

3. What Is NOT Stable in V1

The following surfaces are shipped today but are explicitly not stable. A V1.1 release is allowed to change them in observable ways. If your CI or production behavior depends on any of these, pin the binary version or plan to revisit at each upgrade.

• Visual rule-graph rendering. The standalone visual rule graph (relations as nodes, derivation and negation edges, stratum boundaries, coverage overlays) ships in V1.1. V1 exposes the surrounding ontology context, but not the interactive graph render itself.
• Visual provenance-graph rendering. Per-fact derivation-tree visualization inside Studio’s drill inspector and Provenance surface ships in V1.1. The data is exported in every verification bundle today; the rendering surface is what changes.
• Querying for missing facts from Studio. Direct “why didn’t this fact derive?” queries inside Studio ship in V1.1.
• Compare-evaluator dual-pane render. The Activity Compare lens chip pins the comparison evaluator’s identity in V1 but does not split the row stream side by side. Dual-pane rendering ships in V1.1.
• Inline negation-witness display. Drill-inspector inline rendering of which negation checks passed or failed ships in V1.1.
• Gaifman Neighborhood view. A graph-centered local-witness view ships in V1.1 alongside the rule graph.
• Standalone contradiction-queue surface. A dedicated contradiction Studio surface ships in V1.1.
• Unsigned macOS bundles on the preview channel. GA macOS-arm64 ships signed and notarized only when Apple signing secrets are configured. The preview channel may publish unsigned macOS bundles per .github/workflows/release.yml. Do not depend on unsigned-preview Gatekeeper behavior in production.
• jacqos export graph-bundle and jacqos export benchmark-report artifact shapes. The CLI commands themselves are stable; the inner JSON shapes are labelled draft local in the published surface inventory and may evolve in V1.x.
• Inspection API individual route shapes. The protocol envelope is versioned (inspection-v1); individual route payloads inside it may evolve additively.

V1 ships these behind clear “V1.1 adds” callouts in the docs so you can plan around them.

4. What Requires V2

The following changes will only happen at the V2 boundary, accompanied by the migration policy in §5. JacqOS will not perform any of these in a V1.x release.

• Changing the evaluator_digest derivation. The digest is defined as hash(ontology IR, mapper semantics, helper digests). Any change to that derivation would invalidate every existing verification bundle and break the cryptographic compare guarantee. V2 only.
• Removing or renaming any V1-stable diagnostic code. Codes in the V1 inventory keep their identity for the lifetime of V1.
• Removing or renaming any V1-stable CLI subcommand or .dh keyword.
• Changing the canonical mapper export shape. The mapper_output_digest is the contract boundary between Rhai source and the rest of the system. Changing the shape would re-digest every existing evaluation package.
• Changing the observation log’s append-only semantics. Observations cannot be edited or deleted in place. Any retention or compaction behavior is layered on top of an immutable log; that invariant is the basis of replay.
• Changing the package_digest definition. The digest of the frozen evaluation package contents is the portable contract boundary; changing its definition would re-identify every shipped package.
• Removing any of the five V1 effect capabilities.
• Changing the verification bundle envelope version. The jacqos_verify_v1 envelope is the V1 contract; a jacqos_verify_v2 envelope would be a V2 surface.

5. Migration Policy

When V2 lands, JacqOS will provide:

• A V1 evaluator compatibility shim for any change touching evaluation digests. Existing fixtures will continue to verify under the V1 evaluator alongside the V2 evaluator for the full deprecation window. Your checked-in generated/verification/ artifacts remain meaningful.
• Source migration tooling for .dh if the grammar changes between major versions. The tool will rewrite V1 .dh source into V2 .dh source mechanically, with diagnostics for any cases that need human review.
• A 12-month deprecation window before any V1-stable surface is removed in V2. During that window, V2 binaries continue to load and evaluate V1 apps with their V1.x semantics, and emit deprecation warnings via diagnostic codes in the WX.. (warning) range that point to the V2-equivalent surface.
• Versioned CI guidance. Release notes for the V2.0 cut will pin exactly which V1.x surfaces remain available, which require migration, and which are removed. CI configurations targeting V1 do not silently start consuming V2 behavior.

JacqOS will not:

• Silently change evaluator_digest outputs across a V1.x boundary.
• Remove a V1-stable surface inside V1.x.
• Ship a V2 release that fails to load a V1.0-conformant app inside the deprecation window.

6. Versioning Scheme: app_version and jacqos_version

Two version strings interact when you build on JacqOS:

• app_version lives in your jacqos.toml manifest. It is a required, non-blank contract field that identifies one revision of your application. JacqOS does not parse it as semver; the string round-trips into every export, evaluation package, and verification bundle. Choose a scheme (semver, calver, build hash) that matches how you ship.
• jacqos_version is the platform binary version, surfaced through jacqos --version. The platform follows semver: MAJOR.MINOR.PATCH. MAJOR increments only at a V1→V2-style boundary and only with the migration policy in §5. MINOR increments for the additive changes in §2. PATCH increments for bug fixes that preserve every promise on this page.

The interaction:

• A V1.x binary loads any V1.0-conformant app without modification.
• A V1.0 binary may fail to load an app that uses V1.x-only .dh keywords, capabilities, or [resources] providers introduced after V1.0. The diagnostic identifies the missing feature and the minimum binary version that supports it.
• evaluator_digest is a function of your app’s semantics, not of jacqos_version. Upgrading the platform across V1.x does not change the digest of an app that has not been edited.
• package_digest is a function of the frozen evaluation package contents. The same caveat applies: V1.x binary upgrades do not re-hash packages.

If your CI compares verification bundles across runs, the relevant pin is the app inputs (your .dh, Rhai, and jacqos.toml). The platform binary version is recorded in the bundle for diagnostic purposes but does not enter the digest. This is the property that lets you upgrade the platform without re-baselining your goldens — for any change covered by §2.

For changes covered by §3 or §4, plan the upgrade explicitly: pin the binary, run the new release in a shadow build, compare the verification bundles, and only promote when you have reviewed any changed digests.

Summary

If you are building on V1.0 today:

• Build against the .dh grammar, the jacqos.toml schema, the CLI surface, the five effect capabilities, the verification bundle, the Rhai Mapper API, and the V1 diagnostic codes. Those are the surfaces JacqOS keeps stable for the V1 lifetime.
• Treat anything in §3 as a “use today, expect movement in V1.1” surface. Do not gate production behavior on the visual rule graph, dual-pane Compare, or unsigned macOS-preview bundles.
• Plan for V2 only when JacqOS publishes a V2 release-candidate. The migration policy in §5 commits to the shim, the migration tooling, and the 12-month window so the upgrade is a planned event rather than a surprise.