# Enterprise Quantity Values

Version 0.1.0. Reviewable draft; an embedded executable profile of selected WM-XCT-008 concepts. The catalogue delivery category companion-contract identifies a shared implementation package. It does not create an independent Quantity, UnitRegistry, Observation, or ConversionReceipt entity. A host object and its field/fact retain all instance identity and lifecycle. Use an existing service estimate, route plan, resource assertion or thermal sample as the host. Those example host types are synthetic, not newly published metamodels.

## Minimum adoption and trust boundary

Start with one existing host, a quantity kind, a resolved unit definition, a contextual basis and a source assertion. No ERP, HRIS or registry server is required. A small host may curate an explicit versioned definition file; a large host may resolve an external governed vocabulary. Resolution, approval, signature verification and network fetching are not implemented here. Never construct an admission list simply by hashing untrusted incoming values.

The mandatory caller argument admitted contains exactly three actual sets or frozensets: definitions, sources, contexts. Each contains lowercase SHA256 hex digests under the local encoding below. A definition entry hashes the entire UnitDefinition object, while source and context entries hash the entire Pin object. Pin.sha256 is an upstream evidence digest under a host-defined byte convention; it is different from the digest of that Pin used for local admission. The host verifies the actual evidence, applicable revision, use purpose and actor before supplying sets. Shape, membership and arithmetic do not authenticate a source or prove a physical measurement. The same sets are current inspection admission; they are not credentials or write authorization. Keep historical source/definition snapshots separately and decide current read and write permissions outside this API.

## Embedded values and reference snapshots

QuantityDocument and ConversionDocument are versioned wire wrappers. Neither has an independent object ID. QuantityValue contains one UnitDefinition, one role, one context Pin, one source Pin and one magnitude. Quantity identity is the host's qualified subject and field/fact; a new display label or conversion does not create a second measured thing.

A Pin is an opaque exact tuple uri, revision, sha256. It is case-sensitive, without URI normalization, alias resolution or Unicode equivalence. URIs are restricted ASCII urn: or https:// references; this grammar is not a network or dereferenceability check. Revision is a nonempty printable ASCII token with no whitespace; its meaning and upstream byte convention are supplied by the host. Hashes bind a declared snapshot to a trusted expected value only after external verification; hashes are not signatures. Synthetic fixture pins use documented deterministic synthetic preimages, not live registry evidence.

UnitDefinition is a local immutable snapshot admitted by the host. reference identifies the unit-definition revision; code preserves its original case-sensitive expression. kind pins the quantity kind, dimension supplies seven integer exponents in order length, mass, time, electric current, thermodynamic temperature, amount of substance, luminous intensity, and anchor pins the common reference coordinate, fixing both origin and coordinate unit/scale. All conversions, including scalar and difference, require identical full kind, dimension and anchor pins. authority identifies the evidence/policy approving this exact transform. These are different references even when one governance system manages them. The code is opaque: no UCUM expression parser, annotation interpretation, QUDT graph resolver or universal code mapping ships. Dimension exponents are restricted to integers from -12 through 12; this is a narrower subset than the parent's rational-exponent field.

roles explicitly permits scalar, point and/or difference. A scalar definition must have zero offset; points use offsets, differences suppress offsets. The host must choose meaningful kind and role together. Definitions may use a temperature-family kind and separate role, or separately governed point/difference kinds. This profile never equates different kind pins automatically. Equal physical dimension does not establish kind compatibility: energy and torque are refused when kind pins differ. A counting subject such as tests or seats belongs to kind/context, not to a UCUM annotation. Explicit unit one differs from an unresolved or missing unit; unresolved units fail closed.

KnownMagnitude contains an ASCII decimal lexical string, its scale, and precisionMeaning. Scale is exactly the number of fractional digits; maximum 36 total digits, of which at most 18 are fractional. Exponents, grouping, leading plus, noncanonical leading zeros and binary floating-point input are refused. Preserve original trailing zeros and signed zero verbatim. Numerically signed zero equals zero; rational output is unsigned zero. reported-digits means only asserted representation, not measured uncertainty or exact physical truth. exact-by-definition is a host assertion and requires domain evidence. Both use exact rational arithmetic on the supplied numeral. Conversion does not infer significant figures, uncertainty, confidence or conformity.

MissingMagnitude has state unknown, withheld or not-applicable plus a reason. It retains the same known unit/context/source contract and can be stored/validated. Arithmetic and comparison refuse it. Unknown unit, kind, role, context or source cannot enter this profile. Preserve such an unresolved assertion in the host; this narrow profile cannot represent it and must not substitute unit one. Blank reason strings are syntactically possible if composed of spaces; their substantive sufficiency is a host check.

## Arithmetic and exact definition authority

UnitDefinition uses the single explicit normal form anchor = a*x + b. a and b are reduced rational pairs n/d, at most 36 characters per component, including any minus sign, positive denominator, canonical zero 0/1; a must be positive. exactness must be definition-exact. Nonlinear/logarithmic, approximate, material-dependent, arbitrary and procedure-dependent transforms are unsupported. A host may not relabel an approximate factor as definition-exact. The validator cannot infer that an admitted rational or source assertion is physically correct.

For a point conversion between definitions with the same entire kind, dimension and anchor, output = (a_source*x + b_source - b_target)/a_target. For scalar or difference, output = a_source*x/a_target; each definition must permit the input role. Result is a reduced rational, maximum 256 characters per component, including any minus sign. The original QuantityValue and target definition are retained inline. No rounded decimal result or significant-digit policy is introduced. The accepted normalized ASCII decimal lexical form is retained. Raw external notation such as grouping, exponents, leading plus, unit glyphs and localized decimals must remain in the host source evidence; normalization into this profile is a separately governed host step. The result is a numeric coordinate in the target unit with the same role, kind and context as the retained input; it is not a new observation or independently sourced assertion. To persist a new assertion, the host must explicitly own and justify it.

UCUM 2.2 sections 30 and 43 give the selected exact Celsius/Fahrenheit transforms. Fahrenheit to kelvin is (x+459.67)*5/9. Normal form therefore has a=5/9 and b=45967/180. Celsius uses a=1 and b=5463/20. A difference of 18 Fahrenheit degrees converts to a difference of 10 Celsius degrees; a point at 32 Fahrenheit converts to a point at 0 Celsius. Raw QUDT source inspected at the pinned commit contains pre-offset 459.67 and a finite decimal multiplier for Fahrenheit. Blindly reading those columns as this profile's b and exact 5/9 is invalid. An adapter must separately justify order and exactness; none is shipped.

compare validates both known quantities, requires identical context and role, then converts to the second unit and returns -1, 0 or 1. This means numeric coordinate ordering only. It does not decide business interchangeability, measurement equality within uncertainty, acceptance tolerance, aggregation permission or safety. General addition/subtraction is not implemented. Point minus point may yield a difference and point plus difference may yield a point in a governed affine space; neither operation is claimed forbidden universally or implemented here. Quantity times price, FX, currencies as units, working calendars and localized presentation remain separate research.

## Executable API and encoding

Use load(bytes) followed by validate(document, admitted=...). load rejects duplicate keys, JSON floating-point/exponent tokens, nonfinite tokens, malformed UTF-8 and oversized bytes. validate checks closed schema, definition/source/context admission and exact replay for conversions. convert(quantity, target, admitted=...) preserves the source and returns a validated ConversionDocument. compare has the restrictions above. canonical(value) implements the local byte encoding; digest(value) returns its SHA256 for trusted definition/source/context admission. These helpers do not resolve evidence or grant admission. These functions perform no I/O. validate is repeatable and returns a defensive copy; this is not a storage import guarantee.

The normative local digest encoding accepts only JSON objects, arrays, printable ASCII strings, integers, true, false and null. Objects have string keys sorted by ASCII code point; no spaces separate tokens. Encode using UTF-8, which is identical to ASCII for these admitted strings. Strings escape double quote as backslash-double-quote and backslash as two backslashes; no other admitted character is escaped, including slash. Integers use decimal digits with optional leading minus, no leading zero except 0; literals are lowercase true/false/null. Lists keep order. A digest is SHA256 over these bytes, rendered as 64 lowercase hex digits. Python reference and small encoding vectors are tested; independent language implementations and RFC 8785/JCS compatibility are not certified.

Each wire document or native envelope is capped at 262144 bytes in this encoding (and incoming raw wire size), depth 24, 32 keys per object, 32 elements per array, 1024 ASCII characters per generic string and integer magnitude 9999. Schema fields have tighter bounds. No central quantity-history register or lifetime quantity count exists. These are per-record reference limits, not production load certification. These bounds apply to the complete quantity fact, but only to the four bound host-object fields recordType, schemaVersion, objectId and accessClass. The host object itself must pass its own V3 outer validation. Its unrelated fields, including non-ASCII name/description, are outside the companion checks. Pass the actual full object; the function inspects those four fields without claiming to validate other host properties.

quantity.py pins its sibling quantity.schema.json before loading. Verify all package assets against a trusted release before execution. This pin is not a signature or hermetic dependency guarantee. Tested Python 3.12.14 and jsonschema 4.26.0; transitive supply-chain hashes and alternative runtime certification are not supplied.

## Native V3 binding, correction and rights

Five operational files are installed: spec.json (including this complete contract and semantic matrices), AGENTS.md, runtime-model.reference.json, quantity.schema.json and quantity.py. The pinned full ZIP contains reproduction scripts, fixtures, evidence and source limits. There is no automatic companion dispatch. First resolve the correct Dimension and host object through authenticated host state and check current access, then run the V3 outer validator, then load and validate the actual stored nested value using validate_native.

This native reference supports ONE semantic quantity per existing host object, with one quantity.value slot and one quantity.conversion slot for that same quantity. The paths are exact and have no field qualifier. Multiple records on those paths are revisions or retained competing assertions of the same semantic quantity, not arbitrary different fields. The host must enforce this slot inventory; validate_native is a single-record checker and does not inspect other stored facts. Do not create artificial host objects merely to evade the limit. A host requiring several quantity fields may use the pure embedded-value API under its own separately specified field binding; that multi-field native adapter is not shipped or tested here.

Store QuantityDocument at quantity.value or ConversionDocument at quantity.conversion on that existing host object. Correcting quantity.value does not automatically refresh or link quantity.conversion. A retained conversion is historical derivation evidence; the host must check its source revision before presenting it as current. No staleness detector or link-maintenance engine is shipped. The nested value is a closed object; outer unit must be null because unit semantics are inside it. Host objectType is intentionally not constrained: the host model owns it. validate_native checks the supplied expected subject against both stored fact.subjectId and object.objectId. Its expected master, writer and access arguments come from authenticated host context, not the incoming record. Fact masterSystem must match master; authority must exactly equal {source: writer, rank: 0}. Access must equal the supplied public/internal/restricted/confidential value on both object and fact. Fact provenance.source must equal the capture master; the nested source Pin concerns semantic input evidence and need not name that capture system. Capturing a source does not transfer semantic ownership.

This bound native subset accepts asserted facts with open-ended validTo=null and strict UTC seconds for recordedAt and validFrom. They are bitemporal host assertion times, not a computedAt or measurement timestamp inferred by this profile. The host governs applicability, clock plausibility and any measurement time in its own model. Supersession uses native immutable fact IDs. Host identity/lifecycle, current object revision, state, fact winner, full supersession graph, permissions, source authenticity and durable storage are not established by this checker. Supplying an old object record is never proof of current access.

For correction, append a new fact on the same host/path with supersedes containing the exact prior fact ID, a distinct fact ID, recordedAt no earlier than the predecessor and nonblank provenance.correctionReason. validate_correction checks these two supplied records and their nested values; it does not discover an omitted earlier record, detect a parallel head, lock storage or establish a complete history. The 0.1.0 correction function uses one expected master, writer and access value for both records, so only same-master, same-writer, same-access corrections are supported. A changed capture actor/system or disclosure class requires a separately governed workflow and is refused by this function. This is a compatibility restriction, not evidence of tampering. It also rejects a directly visible two-record supersession cycle; longer cycles and full graph closure remain host work. The host may correct source or unit-definition revision only while preserving those semantic pins/role/context, retaining original bytes and governing applicability times. Pairwise correction preserves the input kind, dimension, anchor, role and context exactly. Changed semantic meaning requires a separately governed workflow; this function rejects it as correction-semantics. No chain-wide closure or authorization is inferred. Inspecting both records requires current admission of their historical references. Incoming write admission is a separate host decision.

The native append tool rejects a duplicate record ID, including an identical repeat. This package does not claim idempotent native import. A future replay adapter must authenticate existing bytes, detect conflicts and decide whether to skip before append. Synthetic acceptance captures predecessor bytes immediately after the first append and checks them after correction append, pair validation and tamper restoration separately. It verifies duplicate refusal, stored correction and outer-only acceptance of an invalid nested arithmetic result that the companion rejects. Retraction, finite-ended intervals, conflict resolution, current selection, host revision migration, retention/tombstones and automatic adapters remain host work.

## Versions, limits and wider composition

Schema/package version, host object identity, fact record identity and external reference revision are separate. Only same-version lossless roundtrip is implemented. Unknown fields and versions fail closed. A new definition revision requires fresh trusted admission; an old snapshot is not silently upgraded. Preserve old facts and validator bytes. Upgrade/downgrade or an algorithm change needs a separately reviewed mapping and new facts, not editing old JSON or changing its version label. Rollback restores the old pinned package and retained data while reevaluating current permissions.

The published parent WM-XCT-008 0.3.0-research.1 is a semantic reference with exact source digest in composition. Ten selected findings and all fourteen function descriptions were inspected; the parent provides declarative semantics, not the code in this release. This is not whole-parent inheritance or UCUM/QUDT/ISO conformance. Parent gaps about uncertainty, domain profiles, mixed external editions and paywalled sources remain open. The wider EM-XCT-06 contour stays partial alongside the separately published monetary calculation package. No completed FX, Price, Calendar or Localization engine is implied.


## Failure handling for adopting agents

Rejected reason codes describe a failed local check, never a finding of fraud or source falsity. Do not automatically retry by replacing data or widening admission. Permission and disclosure govern diagnostics as well as successful values.

| Reasons | Meaning and next step |
|---|---|
| wire-bytes, wire-json, duplicate-key, wire-float, wire-integer | Preserve original evidence; request valid bounded JSON without duplicates or numeric coercion. |
| depth, object-bounds, array-bounds, ascii-string, integer-bounds, unsupported-number-or-type, bytes | Outside the reference representation/resource subset. Keep raw source in the host; use a separately specified normalization or compatible profile. |
| schema, schema-pin | schema means unsupported shape/version or transform class, including formula/exactness constant failures; inspect the supplied field and route unsupported transforms to the host assertion owner. schema-pin specifically means a changed sibling schema: check trusted release bytes. Never disable pins or relabel versions. |
| noncanonical-rational, positive-factor, scalar-offset, scale, decimal-bounds | Correct representation only with source/definition authority; preserve the rejected original separately. |
| admission-shape, admission-set | Host integration supplied malformed sets. Repair the authenticated context builder, not the record. |
| definition-not-admitted, source-not-admitted, context-not-admitted | Required snapshot is not currently admitted for inspection. Resolve its exact evidence, scope and rights with the owner; revocation does not mean the historical fact was corrupt. |
| kind-mismatch, dimension-mismatch, anchor-mismatch, role-not-admitted, target-role, context-mismatch, role-mismatch | Local compatibility is absent. Request a governed mapping or correct contextual basis; do not equate labels or dimensions automatically. |
| non-numeric | Missing magnitude remains explicit; no calculation until evidence exists. |
| replay-mismatch | Retained result disagrees with supplied input/definition under this algorithm. Preserve bytes and investigate; no automatic replacement or approval. |
| native-shape, native-context, native-id, native-version, native-subject, native-master, native-access, native-state, native-path, native-provenance, native-time | Recheck the real stored record, its outer V3 validation and authenticated expected binding. Same-writer/master/access and open-ended asserted facts are deliberate restrictions. A mismatch alone does not establish wrongdoing. |
| correction-link, correction-cycle, correction-path, correction-semantics, correction-time, correction-reason | Preserve both records; resolve predecessor, chronology and reason under host authority. Full history and current winner still require host checks. |

Before admitting input, the host must bind its authenticated source evidence to the asserted magnitude, role, kind and context of this exact subject/use. A Pin membership alone does not check that semantic relationship. Do not share broad admission sets across subjects or purposes without an explicit host decision. Example fixture sets are not an evidence resolver.

Synthetic composition fixtures declare publicationStatus=published only to exercise the installer. That declaration is simulated candidate state, not production publication evidence; actual HTTP/catalogue verification is a separate release record.