Unit definitions and conversion

Units & Quantities (UUCE)

Preview: execute standalone conversions from a pinned unit snapshot through REST or MCP. Existing calculators continue to use their published contracts.

304 definitions · 68 quantity kinds. Browse Unit Directory →

Conversion execution Preview

Download the public CVP replay packs to recompute listed unit conversions offline with the open-source CVP CLI. Every definition in 0.3.0-preview.3 appears in a successful case. The cases include same-unit conversions for quantity kinds with a single registered unit.

Send a JSON POST to /api/v1/units/convert. In MCP, search for a unit pair, inspect units.convert, then call execute_calculation with that capability ID and the same envelope. The optional calculation version pins the arithmetic policy. The required snapshot version pins the definitions.

{
  "calculation_version": "0.1.1",
  "inputs": {
    "value": "1",
    "from_unit_id": "cx:m",
    "to_unit_id": "cx:ft_i",
    "quantity_kind": "length",
    "role": "scalar",
    "snapshot": "0.3.0-preview.3"
  }
}

This request converts 1 metre to exactly 1250/381 international feet. NIST defines the international foot as exactly 0.3048 metres. UUCE divides the source scale by the target scale for a scalar conversion. NIST conversion factors

Use decimal text, stable unit IDs, an explicit quantity kind, and a scalar, point, or interval role. Search returns candidate IDs when a name is ambiguous. The execution contract requires the caller to choose an ID. Temperature points below absolute zero return a domain error.

The result includes an exact reduced fraction times π^pi_power, a decimal string rounded to 34 significant digits using ties to even, and a binary64 number when representable. For expressions containing π, both numeric representations use a fixed high-precision approximation of π. The receipt identifies the definition snapshot, executable projection, integrity manifest, both unit revisions and dependency digests, and the numerical policy. verification separates CVP assessment from production binding. Inspect returns the input, success and error schemas.

The conformance vectors for 0.1.1 document exact reference relations and API edge cases. Use the file's calculation_version with each case's inputs unless the case overrides the version to check a rejection. The historical 0.1.0 vectors remain available for audit.

CVP verification covers the cases and rejection partitions listed in the historical CVP Manifest. The current Manifest projection shows the current production binding for this version. Check the versioned production receipt against your trusted release pins. The full production attestation and the human-readable Evidence report remain available for audit.

Preview covers compatible linear and affine definitions, including registered compound units. Arbitrary expression parsing and conversions that need model inputs are outside its scope.

Agent preflight

GET /api/v1/units/preflight returns the versioned policy and its machine-readable scope. Version 1.0.0 covers scalar length conversions in either direction between cx:m and cx:ft_i. It accepts decimal text from 0 through 1,000,000 with up to 12 fractional digits and requires the caller to establish a standalone, low-risk use.

1. Pin the calculation and policy versions plus the CVP profile, revision, full CVP core digest, registry version, definition digest, execution projection digest, integrity manifest digest and numerical policy using a release you already trust. Use the historical Manifest and public replay pack to establish those pins.
2. Send a JSON POST to /api/v1/units/preflight with policy_version, calculation_version, the regular conversion inputs, your pins in trust using the same keys as the receipt's binding. Set context.use_case to standalone_low_risk when the caller has established that context.
3. Proceed only on ALLOW. Use the returned execute request before the receipt expires. Match the response version, CVP core digest, revision, numerical policy and snapshot to your pins. On NEED_CONTEXT, resolve the listed fields before trying again. Treat DENY, an unavailable response or any unexpected decision as a stop for automatic use.

The production origin issues the receipt over HTTPS as a compact projection of the matching production probe. The receipt expires 7 days after that probe completed. A published stale or superseded binding withdraws it earlier. Fetch a fresh decision before every automatic call. The receipt carries no standalone signature and the preflight relies on the use case declared by the caller. This policy is opt-in for clients that call REST or MCP.

Fixed snapshots

Current snapshot: 0.3.0-preview.3. Versioned files are retained; a changed file requires a new registry version. Fetch these URLs directly rather than extracting data from hashed browser bundles.

• Authored definitions: the exact source document used for definition digests.
• Source JSON Schema: validates the authored document, not the enriched projection.
• Public registry projection: normalized transforms, sources, definition and dependency digests.
• Digest verification example: public definition-data checks only; Node.js 18 or later.

Projection integrity

The execution snapshot integrity manifest binds the authored definitions, full registry projection and the data projection used by the engine. Download the projection verifier and keep it alongside verify-digests-v3.js. The verifier rebuilds the execution fields from the authored snapshot before comparing the published projection.

node verify-projection-v1.js definitions.json registry.json integrity-v1.json <trusted-manifest-sha256>

Obtain the expected canonical manifest digest from a release record you trust. The digest for this published Preview is ec4360ac1db7cfa18550d955fe4afca333295b74b2348bfd6a40cf8419d0aef0. A digest obtained alongside the files checks consistency within that distribution.

Identity and scope

Use unit_id as identity within a pinned snapshot. Slugs identify pages; codes and symbols are case-sensitive. Aliases help discovery and do not authorize ambiguous execution. Unicode spellings are explicit aliases: this contract does not apply global case folding, NFKC normalization, implicit prefixes or an expression parser.

Schema 1.2.0 keeps IDs, slugs and registry codes unique. The projection's lookup separates unit_id, code, symbol and alias namespaces. Each token maps to an array of candidate IDs. Shared ft and minute tokens must not silently select a definition. Use an explicit namespace and quantity kind, then require one candidate. These are definition-data lookups, not a public execution endpoint.

A canonical unit may declare applicable_quantity_kinds, including its primary quantity_kind. The projection exposes these as quantity_kinds. For example, cubic metre serves volume and section modulus without duplicating its definition. Every declared kind must have the same dimension and roles, and the reference unit must support all of them. The model field still chooses the quantity kind; this is not permission to exchange values between different quantities.

Dimension vectors use the order length, mass, time, electric current, thermodynamic temperature, amount of substance, luminous intensity. Equal vectors do not by themselves establish quantity-kind compatibility. Domains are discovery tags; owner packages identify maintainers.

Point values use scale and offset. Intervals use scale only. The directory describes these roles; linked legacy tools continue to use their own contracts. The data snapshot does not make them UUCE operations.

Definition digest contract v2

Schema 1.1 coefficients may include pi_power on scales: numerator / denominator × π^pi_power. Omitted power means zero; nonzero powers are integers from −12 to 12. This restricted exact form represents degree, arcminute, arcsecond, turn and gon without rounding π. Offsets remain rational. This is definition arithmetic, not a general symbolic algebra engine or an execution precision policy. Plane angle, solid angle and ratio remain different quantity kinds even though their SI dimension is 1.

Schema 1.2 adds explicit expression_roles for temperature factors. A kelvin or Celsius factor inside heat capacity or conductivity must declare interval; only its scale participates. Temperature points remain forbidden in products. Orphan roles and roles unsupported by the referenced unit are rejected. Displayed ΔK or Δ°C indicates this role.

The algorithm is SHA-256 of UTF-8 JSON with no whitespace or final newline. Recursively sort object keys using JavaScript string order; retain array order. Strings are not Unicode-normalized. Coefficients are decimal integer strings, not floating-point numbers. This is the CalculatorX v1 serialization rule, not a claim of RFC 8785 conformance.

1. Registry content digest: hash the entire authored definitions document.
2. Definition content digest: hash the authored unit record after reducing its transform scale and offset to coprime fractions with positive denominators, retaining a nonzero pi_power on nonzero coefficients and omitting a zero power. This preserves the schema 1.0 rule for rational definitions.
3. Definition dependency digest: start with that record, recursively include reference units and expression factors, de-duplicate and sort unit IDs. Hash an object containing definitions (authored records in ID order), kinds (all applicable kind records sorted by ID) and sources (referenced source records sorted by ID).

Definition content includes aliases, scope and source locators as well as mathematical coefficients. Source metadata affects dependency and registry digests. Editing a kind's domain tags affects dependency digests without changing unit content digests. Generated display prose is outside these digests. Digests establish content identity; they do not authenticate the publisher or prove numerical correctness.

node verify-digests-v3.js definitions.json registry.json

The v3 example checks schema 1.0, 1.1 and 1.2 snapshots. Schema 1.2 projections declare calculatorx-unit-definition-digests-v2, binding all applicable kinds in the dependency closure. Earlier snapshots use digest contract v1 with only the primary kind. The original v1 and v2 examples remain available for the retained 0.1.0 and 0.2.0 previews. Definition counts exclude aliases and conversion pairs. Systems and current/historical usage are browsing metadata; neither establishes operation compatibility or CVP status.

Compare the reported registry digest with a value obtained from a trusted channel. Editing both downloaded documents and recomputing all digests cannot be detected by an internal consistency check alone.

Calculator field bindings

Participating Math capabilities expose a unit_contract through inspect_capability and REST result_detail; MCP execution includes it in both result and result_detail. This is a set of field declarations, including inactive operation branches. Paths are relative to inputs or the result value: dots separate properties, * denotes array items, and $ denotes a scalar result.

Fixed fields reference pinned UUCE IDs, revisions and content/dependency digests. Angular selectors preserve the existing deg/rad choice and default. Percent values use cx:percent; fractional ratios use cx:one. A result obtained by solving for an amount does not inherit a percentage unit. Abstract geometry keeps consistent input units and their squared/cubed derivatives; it does not silently choose metres. These declarations do not run conversions, change angle wrapping or extend numerical certification.

Versions and review state

The contract and records remain Preview. Pin a registry version and check its digest. Definition-content edits require a new unit revision and registry version; source or kind metadata changes require a new registry version. Do not reuse an identity for a different unit. Retired definitions retain their old snapshots; automated replacement and cross-version compatibility are not promised.

Candidate is a definition lifecycle state, independent of conversion availability and Capability@Version verification. Public worked examples and Evidence summaries are separate from private CVP cases, oracles and checkers. This download does not expose or replay the private validation suite.

Browse the Unit Directory · CVP scope