# Enterprise Monetary Calculation — semantic contract

Version 0.1.0. Bounded original companion, reviewable draft. One independent type: MonetaryCalculationReceipt. It records a calculation of already asserted exact monetary inputs; it does not create a second monetary master. Install only when the host needs a durable independently addressable calculation receipt. An existing calculation or audit record may use this as a design checklist; no host adapter or automatic identity mapping is specified. Do not duplicate it automatically for every money field.

## Identity, inputs and result

A receipt has an immutable request.id qualified by Dimension. New computation or correction gets a new ID. Same ID with different content is a conflict. IDs use a restricted lowercase URN grammar; no case folding or alias equivalence is inferred. The subject is the externally owned estimate/reconciliation aggregate whose independently established identity and policy justify combining the amounts. It must not be an arbitrary dashboard collection. Input sources identify exact monetary slots, not merely whole documents: assign a distinct qualified source slot ID and revision/digest for every input. Source-slot IDs must be unique inside a request; identical amounts from different slots are legitimate. One source used twice is refused rather than silently double counted.

Each input binds amount lexical string, explicit decimal scale, exact state, currency reference, source pin and valuation context. Its host owns the underlying assertion. Currency equality means the entire catalogue, edition, snapshot digest and code tuple matches. Currency resolution is explicitly host-admitted: this package does not contain an ISO list, fetch a register, prove that a code exists or validate its transaction eligibility. Arbitrary unadmitted inputs must never be relabeled host-admitted by an untrusted caller. Unknown, absent, approximate and interval monetary values are unsupported; preserve them in the host and request missing facts, never map them to zero. Input source truth, exactness and allowed sign are host assertions, not established by decimal syntax.

All valuation contexts must match exactly: basis pin, UTC valuationAt and amountRole. This is a necessary local compatibility check, not proof that the host permits aggregation. The same currency alone does not establish compatible accounting meaning. No accounting, tax or statutory rule is inferred. Policy carries an explicit authority pin, currency, increment, mode and stage. Its authority and substantive applicability require host resolution. The increment is a positive exact decimal; it is never inferred from a currency code or locale. An increment 0.05 is a mathematical quantizer, not a cash-rounding compliance claim.

Decimals are ASCII lexical strings, no exponent, no grouping, no binary floats, at most 36 total digits and 18 fraction digits. Input trailing zeros and declared scale are preserved verbatim. Negative zero is refused. Zero is allowed only as an explicitly asserted exact value. Integer/Fraction arithmetic has no ambient Decimal context. Five modes: half-even ties to an even integral increment count; half-away-from-zero ties away from zero; toward-zero truncates the integral increment count; floor chooses the lower multiple; ceiling the upper multiple. Negative values follow these mathematical definitions; their business meaning is external.

For per-item, quantize every input to an integral multiple of the increment and then sum the quantized values. For after-sum, sum exact inputs first and quantize once. There are no other operations. Multiplication of quantity by price, FX, allocation and tolerance judgments are deferred. An upstream exact line amount such as 0.495 is retained as an input, not claimed to have been computed from a physical quantity by this package.

Result stores exactTotal as a reduced rational, roundedTotal at the increment's lexical decimal scale, signed residual = exactTotal minus roundedTotal, ordered step results/residuals and an inexact flag. Inexact means at least one quantization step changed numeric value; it remains true when per-item residuals cancel at the total. Scale-only representation changes do not set inexact. Output negative zero is normalized to unsigned zero by arithmetic; original negative zero inputs are refused. The result is marked calculation-only. No result chooses a master, pays, posts, staffs or grants access.

## Time, correction and evidence

Schema version, external reference revision, receipt identity and host lifecycle are distinct. computedAt and valuationAt are separate instants, strict UTC seconds, Gregorian dates without leap seconds. Future valuationAt is allowed for an estimate; host clock and semantic checks govern plausibility. Source and policy pins are opaque exact references, not automatically fetched or authenticated. A hash proves byte identity only against a trusted expected value, not authorship or truth.

issue(request) computes and seals a new receipt without I/O. validate(receipt) checks closed schema, digest and exact replay; load(wire) additionally rejects duplicate JSON keys and non-finite literals. Use load before validate on inbound bytes. This canonical JSON is a local deterministic encoding, not an RFC 8785 or digital-signature implementation.

import_receipts(existing, incoming, dimension, admitted_existing_issuers, admitted_incoming_issuers) validates a supplied complete local register, detects ID conflicts and checks supersedes pins, subject and issuer continuity, chronology and acyclicity. Exact replay is idempotent. Both distinct issuer-admission sets must come from the authenticated trusted host; it is only an admission assertion, never a credential or access-control engine. Existing entries use admitted_existing_issuers; incoming entries use admitted_incoming_issuers. Retaining a former issuer in the first set does not allow new incoming records from that issuer. Even exact incoming replay requires incoming admission. Both decisions remain external host assertions. Import does not write storage, lock, enforce append-only media or discover an omitted predecessor. Store completeness, authentication, source resolution, per-object write permission and transaction/CAS remain host duties.

Correction requires a new ID, exact supersedes pin and nonblank reason. The old receipt remains byte-identical and retains its original context. A successor must have the same subject and issuer, and computedAt no earlier than predecessor. Changing issuer requires a separately governed adoption workflow; this implementation refuses a same-chain issuer change. Branching successors are retained; no current winner is inferred. Status is issued implicitly in the receipt format; superseded/withdrawn/current status is an external governance projection. No mutable status or native fact supersession changes the old receipt. No automatic withdrawal, deletion, tombstone or current-effective selector is shipped. All required predecessors must be retained for a closed import; do not silently partition history.

## Bounds and native use

At most 256 inputs per receipt; at most 256 existing and 256 incoming records per call, and at most 256 unique receipt IDs after merging. Exact replay does not consume an additional unique slot. Maximum 2 MiB for each wire record or native envelope, nested depth 16, 512 characters per generic string; schema has tighter field limits. The output has at most 57 digits. The 256-record merge limit is a reference limit, not enterprise storage scale. Byte/cardinality caps are fail-closed bounds, not denial-of-service certification. A trusted prior snapshot is needed to detect replacement of a leaf record. No retention execution exists.

Native V3 stores each receipt as its own object and one restricted monetary.calculation.receipt fact. Native validity time describes receipt storage, not underlying valuation. Preserve computedAt and valuationAt inside the receipt. Outer V3 validation alone cannot validate nested replay. Invoke validate_native for envelope bindings and import_receipts for the complete register in addition to the V3 validator. Install is five operational assets; read this full pinned package, including adoption-limits.md, before using those assets. There is no automatic validator dispatch or existing-Dimension migration. Current read permission is required to inspect historical receipts and diagnostics, which may contain sensitive financial facts.

## Migration and minimum use

Minimum useful configuration: one subject, one receipt, one exact monetary input, one admitted currency/context and one explicit rounding policy. No ERP or HRIS is required. Three synthetic profiles exercise startup line rounding, matrix reconciliation with negative amounts and AI estimate precision; none represent real company internals. Run python test_monetary.py with Python 3.12.14 (tested) and jsonschema 4.26.0. Native verification is a separate acceptance.py run with the exact tool-pins.json toolchain.

Only same-version lossless roundtrip is implemented. Unknown versions and unknown fields fail closed. Upgrade/downgrade needs an explicit future mapping, preservation of old bytes and recomputation under a new receipt ID; never edit a version label or reseal an earlier issuer's result as if it were their approval. Rollback restores the prior complete verified register and original validator, not an obsolete authorization.

## Bounded native and storage contract

This reference has a hard lifetime limit of 256 receipt IDs per Dimension, including every correction and historical receipt. It requires the complete Dimension-wide register for this model. Splitting registers or omitting old leaves loses same-ID conflict detection and is unsupported. This is a bounded adoption fixture, not a production store; production paging/indexing/retention requires a separately reviewed design.

validate_native binds the genesis object record only. It does not discover or authenticate the current head, later object revisions, current access/state, or later fact supersession. Object revision, retirement and native retraction are outside this version. A trusted host must inspect full native history and current permissions before access; passing an old genesis record never proves current access. Native record timestamps are strict UTC seconds, without fractional seconds.

The same closed resource bounds apply to receipt JSON and native envelopes: depth 16, 32 keys per object, lists at most 256, generic strings at most 512 characters, integer magnitude at most 9999, and 2 MiB canonical/wire size. This intentionally accepts a narrower envelope vocabulary than general V3. Schema-specific bounds may be tighter.

## Trusted interpretation

The host must bind the authenticated actor to request.issuer before admitting incoming records: membership in a supplied set does not authenticate a self-declared issuer. Source pins also need a host-defined byte preimage and revision convention. Do not feed a receipt output into a new input as source truth unless the source-owning host explicitly re-asserts that amount under its own source-slot identity and evidence. Any output-changing algorithm fix requires a new package/schema version and new receipt identities, preserving old bytes.

monetary.py checks the SHA256 of its sibling schema before import. This detects a changed schema relative to trusted code; it is not a signature or a trust bootstrap. Verify the entire package manifest from a trusted origin. jsonschema is version-pinned but dependency supply-chain hashes are not supplied by this package.