@affiant/core 0.1.0-alpha.0

package/dist/model/amendments.js

@@ -0,0 +1,183 @@
+/**
+ * Amendments: what a reviewer's correction means, and what it does to the record.
+ *
+ * **Rules served: DK-2** (in an amendment map `null` means *cleared* and an absent
+ * key means *untouched*, and an implementation never conflates them), **AF-1** (a
+ * field with unknown provenance is present and tagged `Empty`; a field the operation
+ * does not propose is absent), **AF-2** (the three numbers, with `Empty` counting as
+ * `0`), **AF-4** (an accepted amendment recomputes the three confidence numbers, and
+ * the amended field's provenance is the reviewer's act — never the machine's
+ * pre-correction tag), **PV-2** (that act carries a `reviewer-act` binding naming
+ * the Docket decision it was made on).
+ *
+ * ## What clearing a field does to the numbers
+ *
+ * A cleared field has no value, so it cannot have confidence in one. Writing the
+ * reviewer's `UserStated`/`1.0` tag over an emptied field would make the three
+ * numbers *rise* as a reviewer wiped the Affidavit — clear every field and the record
+ * reports perfect confidence over nothing, which is the arithmetic hole AF-2 exists
+ * to close, arriving through the amendment path. So a clear is resolved against the
+ * field rather than pasted onto it:
+ *
+ * - **A mandatory field stays and is tagged `Empty`** (confidence `0`, AF-1). The
+ *   entity still requires it, so it is still proposed and still on the card — now
+ *   visibly with nothing behind it, counted in `emptyFieldCount` and dragging
+ *   `aggregateConfidence` to `0`.
+ * - **An optional field is removed from `fields[]`** (AF-1). A reviewer clearing an
+ *   optional field is saying "do not write this one", which is a field the write no
+ *   longer proposes, and AF-1 says a field the operation does not propose is absent
+ *   rather than present-and-`Empty`.
+ *
+ * Either way the reviewer's act is not lost: the `Empty` tag carries the same
+ * `reviewer-act` binding and the same note a set would (PV-2), and the machine's
+ * displaced tag stays in the chain behind it.
+ *
+ * Why DK-2 needs saying at all: `undefined` and `null` are one keystroke apart in
+ * JavaScript and `{ Status: undefined }` reads to a careless consumer as "clear
+ * Status", when it is in fact "say nothing about Status". Conflating them silently
+ * either wipes a field nobody asked to wipe or ignores a correction a person made
+ * on purpose. So this module resolves a map into {@link Amendment} values — `set`
+ * or `clear`, both explicit — and a field nobody amended is simply not in the
+ * resolved list. `undefined` under a key is refused, loudly.
+ *
+ * Why AF-4 needs saying: the shipped demo hosts return an amended Affidavit still
+ * carrying the machine's pre-correction confidence, so a card can show a corrected
+ * value under a number that was never about that value.
+ *
+ * @packageDocumentation
+ */
+import { mintTag, supersede } from "./provenance.js";
+import { withConfidence, } from "./affidavit.js";
+/** Whether `map` says anything at all about `fieldName` (DK-2). */
+export function hasAmendment(map, fieldName) {
+    return Object.hasOwn(map, fieldName);
+}
+/**
+ * Resolve `map` into explicit {@link Amendment} values, in the map's own key order.
+ *
+ * @throws RangeError if a key is present holding `undefined` — the one thing an
+ *         amendment map may not say, because it is indistinguishable at a glance
+ *         from both of DK-2's meanings and is neither.
+ */
+export function resolveAmendments(map) {
+    const resolved = [];
+    for (const name of Object.keys(map)) {
+        const value = map[name];
+        if (value === undefined) {
+            throw new RangeError(`DK-2: amendment ${JSON.stringify(name)} is undefined; ` +
+                `use null to clear the field, or omit the key to leave it untouched`);
+        }
+        resolved.push(value === null
+            ? { name, amendment: { kind: "clear" } }
+            : { name, amendment: { kind: "set", value } });
+    }
+    return resolved;
+}
+/**
+ * The provenance tag an accepted amendment puts in force on the field it names
+ * (PV-2, AF-2).
+ *
+ * One function so there is one answer. The canonical form (SR-1) is defined over
+ * "the Affidavit and its accepted amendments", and an implementation that minted a
+ * *nearly* identical tag on the serialization path would produce different bytes
+ * from the same decision — which is the one thing a canonical form exists to make
+ * impossible. `model/canonical.ts` calls this, and so does {@link applyAmendments}.
+ *
+ * A set mints `UserStated` at confidence `1`: a reviewer typing a value is the
+ * person stating it, and PV-3 makes that the one place the grade is legitimate. A
+ * clear mints `Empty` at confidence `0`: an emptied field has no value to be
+ * confident in, so a clearing can never raise a confidence number.
+ *
+ * Either way the binding is `reviewer-act`, naming the decision *and the instant*,
+ * so an auditor can follow a clearing as readily as a correction.
+ *
+ * @param amendment        What the reviewer did to the field.
+ * @param act              The decision it arrived on.
+ * @param conversationTurn The turn the Affidavit belongs to, carried onto the tag.
+ */
+export function amendmentTag(amendment, act, conversationTurn) {
+    const cleared = amendment.kind === "clear";
+    return mintTag({
+        source: cleared ? "Empty" : "UserStated",
+        confidence: cleared ? 0 : 1,
+        note: cleared
+            ? `Cleared by ${act.by} on Docket entry ${act.entryId}`
+            : `Amended by ${act.by} on Docket entry ${act.entryId}`,
+        at: act.decisionAt,
+        conversationTurn,
+        binding: { kind: "reviewer-act", ref: { entryId: act.entryId, decisionAt: act.decisionAt } },
+    });
+}
+/**
+ * Apply `map` to `affidavit` as `act`, returning a new Affidavit.
+ *
+ * What happens to a field the reviewer **set**: its value becomes the amended value,
+ * and a `UserStated` tag carrying a `reviewer-act` binding goes **on top of** its
+ * chain (PV-2, AF-4). On top rather than merged: a reviewer's correction is not a
+ * confidence contest it might lose to the machine's own tag, and the displaced tag
+ * stays in `prior` so the card can still show what the machine had proposed.
+ *
+ * What happens to a field the reviewer **cleared** (`null`, DK-2): a mandatory field
+ * keeps its place with value `null` under an `Empty` tag at confidence `0`, and an
+ * optional field leaves `fields[]` entirely. See the module note above for why the
+ * reviewer's `1.0` is not written over an emptied field.
+ *
+ * What happens to everything else: nothing. A field the map does not name keeps its
+ * value, its `previousValue` and its whole chain, byte for byte (DK-2). And
+ * `previousValue` never moves — it is what the entity holds now, which an
+ * amendment does not change.
+ *
+ * The three numbers are recomputed over the amended fields (AF-4).
+ *
+ * @throws RangeError if `map` names a field the Affidavit does not propose. Not an
+ *         {@link AffiantError}: the error-code registry names refusals the gate
+ *         makes at runtime about a proposal's substance or a decider's identity,
+ *         and this is a caller passing a field name that is not there — a
+ *         programming error, in the same class as an out-of-range index.
+ */
+export function applyAmendments(affidavit, map, act) {
+    const resolved = resolveAmendments(map);
+    if (resolved.length === 0)
+        return affidavit;
+    const byName = new Map(resolved.map((entry) => [entry.name, entry.amendment]));
+    for (const name of byName.keys()) {
+        if (!affidavit.fields.some((field) => field.name === name)) {
+            throw new RangeError(`amendment names field ${JSON.stringify(name)}, which this Affidavit does not propose`);
+        }
+    }
+    const fields = affidavit.fields.flatMap((field) => {
+        const amendment = byName.get(field.name);
+        if (amendment === undefined)
+            return [field];
+        // AF-1: a cleared optional field is a field the write no longer proposes, so it
+        // is absent rather than present with nothing in it.
+        if (amendment.kind === "clear" && !field.isMandatory)
+            return [];
+        const cleared = amendment.kind === "clear";
+        const value = cleared ? null : amendment.value;
+        const tag = amendmentTag(amendment, act, affidavit.conversationTurn);
+        return [
+            {
+                name: field.name,
+                kind: field.kind,
+                value,
+                previousValue: field.previousValue,
+                provenance: supersede(field.provenance, tag),
+                isMandatory: field.isMandatory,
+            },
+        ];
+    });
+    // AF-4: the numbers are the amended Affidavit's, not the proposal's.
+    return withConfidence({
+        // SR-4: an amendment corrects values, never the version the record conforms
+        // to. Carried through so the accepted state canonicalizes to the same bytes
+        // the same record would on the wire.
+        protocolVersion: affidavit.protocolVersion,
+        operationType: affidavit.operationType,
+        entityType: affidavit.entityType,
+        entityId: affidavit.entityId,
+        conversationTurn: affidavit.conversationTurn,
+        createdAt: affidavit.createdAt,
+    }, fields);
+}
+//# sourceMappingURL=amendments.js.map

package/dist/model/amendments.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"amendments.js","sourceRoot":"","sources":["../../src/model/amendments.ts"],"names":[],"mappings":"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"}

package/dist/model/canonical.d.ts

@@ -0,0 +1,311 @@
+/**
+ * The canonical form of an Affidavit and its accepted amendments, and the SHA-256
+ * hash over it.
+ *
+ * **Rules served: SR-1, SR-2, RT-1.**
+ *
+ * **SR-1** — *the canonical form of a filed proposal is a deterministic byte
+ * sequence over the Affidavit **and its accepted amendments** (the amended field
+ * values with their reviewer-act tags, in the same field order), with UTF-8, object
+ * keys sorted by Unicode code point, no insignificant whitespace, numbers as their
+ * shortest round-trip decimal representation, `null` written and absent omitted.
+ * `canonicalHash` is the SHA-256 of that form.*
+ *
+ * **Why the amendments are inside the form and not beside it.** A host's execution
+ * grant binds to `canonicalHash(Affidavit + amendments)`. If the form covered the
+ * Affidavit alone, a grant minted for the proposal a reviewer *was shown* would
+ * still validate the proposal they *amended* — the one substitution the whole
+ * framework exists to prevent. Two conformance fixtures in this package's vector
+ * set differ only by an amendment, and their hashes differ; that is the rule made
+ * checkable. On a Docket row the same thing is spelled {@link canonicalizeEntry}:
+ * the row keeps the proposal and the accepted state separately, and the form is
+ * taken over the accepted state where there is one.
+ *
+ * **What the form is taken over: the Affidavit as the schema defines it.** Every
+ * property of the record is in the bytes, `protocolVersion` included — the schema
+ * requires it on an Affidavit, and the promoted byte vectors carry it. The card
+ * *envelope*'s presentation is not: `allowedValues`, `pattern`, `warnings` and
+ * `requiresConfirmation` are a host's rendering of a proposal rather than its sworn
+ * substance, and putting a rendering decision inside a hash a grant is checked
+ * against would let restyling an input invalidate a grant minted over evidence that
+ * did not change. Until this version the runtime model omitted `protocolVersion`
+ * and only `toWire` stamped it, so the bytes a Docket row's hash was taken over
+ * were not the bytes of the same record on a card. The model carries it now
+ * (`model/affidavit.ts`), and both paths produce one document for one record.
+ *
+ * **What applying an amendment does, exactly**, is `model/amendments.ts`'s answer and
+ * not this module's: the tag in force comes from `amendmentTag`, so the bytes a
+ * decision produces here and the row that decision writes cannot disagree. That
+ * carries AF-1's clearing rule with it — a cleared **mandatory** field stays, tagged
+ * `Empty` at confidence `0`, and a cleared **optional** field leaves the field list,
+ * because a field the write no longer proposes is absent rather than present with
+ * nothing in it — and AF-4's recompute, where the document carries an aggregate.
+ *
+ * **Why a canonical form at all.** Three things depend on two independent
+ * implementations agreeing byte for byte: the conformance suite compares canonical
+ * forms across the .NET and TypeScript lines; an `utterance-span` provenance
+ * binding hashes the span it points at, so an auditor can re-derive it years later;
+ * and the execution grant above. `JSON.stringify` cannot do any of that — its key
+ * order is insertion order, so the same Affidavit built by two code paths produces
+ * two different documents and two different hashes.
+ *
+ * ## The form, precisely
+ *
+ * A JSON document with no space, tab or newline between tokens. Within it:
+ *
+ * - **Objects** — `{`, then each own enumerable string-keyed property whose value is
+ *   not `undefined`, sorted by **Unicode code point** of the key, as `"key":value`
+ *   separated by `,`, then `}`. Sorting by code point rather than by UTF-16 code
+ *   unit matters above U+FFFF: a key starting with an emoji sorts *after* a key
+ *   starting with U+E000, though a naive JavaScript `<` puts it first. Symbol keys
+ *   are not JSON and are ignored; inherited properties are not own properties and
+ *   are ignored.
+ * - **Arrays** — `[`, elements in their own order, separated by `,`, then `]`.
+ *   Array order is data, never sorted. An `undefined` element is refused rather
+ *   than written as `null`: "absent omitted" is meaningful for a property and
+ *   meaningless for a position, and silently substituting `null` would put a value
+ *   on an audit record that the producer never wrote.
+ * - **Strings** — JSON escaping and nothing more: `"` and `\` escaped, the C0
+ *   control characters escaped (`\b`, `\t`, `\n`, `\f`, `\r`, else `\u00xx` with
+ *   lowercase hex), unpaired surrogates escaped as `\udxxx`. Every other character
+ *   is written as itself and encoded as UTF-8 — **no `\u` escapes for non-ASCII**,
+ *   so `"é"` is two bytes and not six, and `/` is never escaped.
+ * - **Numbers** — the shortest round-trip decimal, written positionally: never an
+ *   exponent, `-0` written as `0`, non-finite refused. See {@link canonicalJson}
+ *   for what "positionally" costs and why it is the safer half of the trade.
+ * - **`null`** — written. **`true` / `false`** — written.
+ * - **Money** — `{ amount, currency }` is two strings (SR-2). A value shaped like
+ *   money whose amount is a number is refused here rather than hashed, because a
+ *   float amount that reached the canonical form would be sworn to.
+ *
+ * ## What is refused
+ *
+ * A non-finite number is a `RangeError`. Everything else that has no canonical form
+ * is a `TypeError`: `undefined` in an array position, a `bigint`, a function, a
+ * symbol, a `Date` or `Map` or typed array (anything whose `Object.prototype.toString`
+ * tag is not `[object Object]` or `[object Array]`), a cycle, and money with a
+ * numeric amount. An audit form never guesses: a value it cannot write exactly is a
+ * value it refuses to write at all.
+ *
+ * ## Integers beyond 2^53 (the documented limit of the rule)
+ *
+ * JSON numbers are IEEE 754 doubles by the time any implementation sees them, so
+ * `9007199254740993` has already become `9007199254740992` in the parser, before the
+ * canonical form is reached. This module therefore writes the shortest round-trip
+ * decimal of the double it was given and **does not** convert large numbers to strings: a
+ * canonical form cannot recover precision the parse already lost, and a form that
+ * quietly restringified some numbers and not others would be harder to reimplement,
+ * not easier. A host that needs exact integers beyond 2^53 — an account number, a
+ * minor-unit amount, an accounting record's id — carries them as strings on the
+ * wire. Money
+ * already does, by SR-2.
+ *
+ * ## Runtime (RT-1)
+ *
+ * `canonicalHash` digests through `globalThis.crypto.subtle`, which has no
+ * synchronous form, so every hash path in this framework is asynchronous end to end
+ * — the stated portability choice, and the reason `canonicalHash` returns a
+ * `Promise` on Node, on Bun and inside workerd alike. No `node:crypto`, no
+ * filesystem, no Node global.
+ *
+ * @packageDocumentation
+ */
+import type { AmendmentMap } from "@affiant/contract";
+import type { DocketEntry } from "../docket/entry.js";
+import type { Affidavit } from "./affidavit.js";
+import type { ReviewerAct } from "./amendments.js";
+/**
+ * One field of the Affidavit, as much of it as canonicalization needs to know.
+ *
+ * Deliberately minimal. This module serializes *whatever object it is handed* —
+ * every own enumerable property, at every depth — so it does not need the Affidavit
+ * type to do its work, and stating a full one here would couple the canonical form
+ * to a model that is still being written (`model/affidavit.ts`, pull request C2).
+ * What it does need is the two properties amendment application reads: the `name`
+ * an amendment is keyed by, and the `value` an amendment replaces. Everything else
+ * on a real `AffidavitField` — `previousValue`, `provenance`, `isMandatory`,
+ * `kind`, `allowedValues`, `pattern` — is carried through untouched and appears in
+ * the bytes, because the bytes are of the object, not of this interface.
+ */
+export interface CanonicalField {
+    /** The field's name. The key {@link AmendmentMap} is keyed by. */
+    readonly name: string;
+    /** The proposed value. Any JSON value, including `null`. */
+    readonly value?: unknown;
+    /** The provenance chain behind the value, if the caller carries one. */
+    readonly provenance?: unknown;
+}
+/**
+ * The Affidavit being canonicalized, as much of it as this module needs to know.
+ *
+ * `fields` is optional so the same function can canonicalize the byte vectors that
+ * exercise the *form* — key ordering, number shapes, escaping — without dressing
+ * them up as Affidavits. A real `Affidavit` from `@affiant/contract` satisfies this
+ * interface structurally, and so will C2's core model.
+ */
+export interface CanonicalInput {
+    /** The sworn fields, in the order the Affidavit carries them. */
+    readonly fields?: readonly CanonicalField[];
+    /**
+     * The protocol version the record conforms to (SR-4).
+     *
+     * Named here — optional, like `fields`, so a bare byte vector need not dress
+     * itself up as an Affidavit — because it is the property whose absence from the
+     * runtime model made the canonical form of a Docket row differ from the canonical
+     * form of the same record on the wire. A real `Affidavit` always carries it; a
+     * record handed here without it is canonicalized without it, because this module
+     * serializes the object it is given and never adds a property to a document.
+     */
+    readonly protocolVersion?: string;
+}
+/** Options for {@link canonicalize}, {@link canonicalString} and {@link canonicalHash}. */
+export interface CanonicalizeOptions {
+    /**
+     * The decision the amendments arrived on — its entry, **its instant** and its
+     * principal. Required whenever a non-empty {@link AmendmentMap} is applied,
+     * because PV-2 says a `reviewer-act` binding names the decision that amended the
+     * field, and a binding that names nothing is not a binding.
+     */
+    readonly reviewerAct?: ReviewerAct;
+}
+/**
+ * Apply an {@link AmendmentMap} to an Affidavit, returning a new object: each
+ * amended field's `value` replaced and the reviewer's own tag put in force on its
+ * provenance chain, with the tag it supersedes preserved beneath it.
+ *
+ * **The tag is `model/amendments.ts`'s, not this module's.** `amendmentTag` is the
+ * single definition of what an accepted amendment does to a field's provenance, and
+ * both paths call it — so the bytes this function produces for a decision are the
+ * bytes the Docket row's own `amendedAffidavit` produces for the same decision.
+ * There is no second, nearly-identical tag to drift.
+ *
+ * **DK-2**: `null` under a key clears the field; an absent key leaves it untouched.
+ * The two are never conflated.
+ *
+ * **AF-1**, on what a clear does: a **mandatory** field keeps its place with value
+ * `null` under an `Empty` tag at confidence `0`, and an **optional** field leaves
+ * `fields[]` entirely — a reviewer clearing an optional field is saying "do not
+ * write this one", and a field the write no longer proposes is absent rather than
+ * present with nothing in it. A field with no `isMandatory` property is read as
+ * optional, which is what the property's absence means everywhere else.
+ *
+ * **AF-4**: every confidence number the document carries — the aggregate, the
+ * populated minimum and the empty-field count — is recomputed over the amended
+ * fields. A canonical form that kept a pre-correction number would let a grant bind
+ * to an Affidavit whose own summary contradicts its fields.
+ *
+ * @param affidavit The Affidavit as filed.
+ * @param amendments The reviewer's accepted amendments, keyed by field name.
+ * @param act       The decision the amendments arrived on (PV-2).
+ * @throws TypeError when the input carries no `fields` array, when a field is not
+ *         an object, or when an amendment names a field the Affidavit does not
+ *         carry — an amendment to something nobody swore to is a bug in the caller,
+ *         and swallowing it would let two implementations disagree in silence.
+ * @throws RangeError when `amendments` holds `undefined` under a key (DK-2).
+ */
+export declare function applyAmendmentsForCanonical(affidavit: CanonicalInput, amendments: AmendmentMap, act: ReviewerAct): CanonicalInput;
+/**
+ * The canonical form of `affidavit` and its accepted `amendments`, as UTF-8 bytes
+ * (SR-1).
+ *
+ * @param affidavit  The Affidavit as filed.
+ * @param amendments The accepted amendments, or `null` / omitted for none. An empty
+ *                   map is the same as none and needs no `reviewerAct`.
+ * @param options    {@link CanonicalizeOptions.reviewerAct}, required whenever
+ *                   `amendments` is non-empty.
+ * @throws RangeError on a non-finite number; TypeError on anything else with no
+ *         canonical form (see the module header).
+ */
+export declare function canonicalize(affidavit: CanonicalInput, amendments?: AmendmentMap | null, options?: CanonicalizeOptions): Uint8Array;
+/**
+ * The canonical form of `affidavit` and its accepted `amendments`, as a string —
+ * the same document {@link canonicalize} returns, before UTF-8 encoding.
+ *
+ * Useful where the bytes are not what is wanted: a fixture that has to be readable
+ * in a diff, a log line, a comparison in a test. The bytes are the contract; this is
+ * the same document one encoding step earlier.
+ */
+export declare function canonicalString(affidavit: CanonicalInput, amendments?: AmendmentMap | null, options?: CanonicalizeOptions): string;
+/**
+ * The SHA-256 of the canonical form, as lowercase hex (SR-1, RT-1).
+ *
+ * Asynchronous on every runtime because Web Crypto has no synchronous digest, and
+ * Web Crypto is the only digest a package that must run on Node, Bun and workerd
+ * can reach (RT-1). This is a stated portability choice, not an oversight: the
+ * .NET line may hash synchronously, since the conformance fixtures assert *values*,
+ * not call shapes.
+ *
+ * @returns 64 lowercase hex characters.
+ */
+export declare function canonicalHash(affidavit: CanonicalInput, amendments?: AmendmentMap | null, options?: CanonicalizeOptions): Promise<string>;
+/**
+ * The Affidavit a Docket row's canonical form is taken over: the state a reviewer's
+ * amendments produced if there is one, and the proposal otherwise (SR-1).
+ *
+ * This is what SR-1's "the Affidavit **and its accepted amendments**" means on a
+ * row. The row keeps both — `affidavit` as the agent proposed it, never edited, and
+ * `amendedAffidavit` as the approval accepted it — so the sworn form and the
+ * proposal are separately readable and only one of them is what a grant binds to.
+ */
+export declare function swornAffidavitOf(entry: DocketEntry): Affidavit;
+/**
+ * The canonical form of a Docket row, as UTF-8 bytes (SR-1).
+ *
+ * Equivalent to `canonicalize(entry.amendedAffidavit ?? entry.affidavit)`, with no
+ * amendment argument: the amendments were applied when the approval was recorded,
+ * by the same `amendmentTag` this module uses, so there is nothing left to apply.
+ *
+ * **This is the function a host's execution grant hashes over.** Binding a grant to
+ * the proposal instead would let a grant minted for the Affidavit a reviewer was
+ * shown validate the one they amended — the substitution the framework exists to
+ * prevent.
+ */
+export declare function canonicalizeEntry(entry: DocketEntry): Uint8Array;
+/** The canonical form of a Docket row as a string — {@link canonicalizeEntry} one encoding step earlier. */
+export declare function canonicalStringEntry(entry: DocketEntry): string;
+/** The SHA-256 of a Docket row's canonical form, as lowercase hex (SR-1, RT-1). */
+export declare function canonicalHashEntry(entry: DocketEntry): Promise<string>;
+/**
+ * SHA-256 over arbitrary bytes, as lowercase hex, through Web Crypto (RT-1).
+ *
+ * Exported because the canonical form is not the only thing this framework hashes:
+ * an `utterance-span` binding hashes the span it points at, so an auditor can
+ * re-derive it, and a host's execution grant hashes what it grants over.
+ *
+ * @throws Error when the runtime exposes no `crypto.subtle` — which, on a runtime
+ *         this package claims to support, means the host has replaced a standard
+ *         global rather than that the digest is unavailable.
+ */
+export declare function sha256Hex(bytes: Uint8Array): Promise<string>;
+/**
+ * The canonical form of any JSON value (SR-1), as a string.
+ *
+ * The general writer the Affidavit entry points are built on, exported because
+ * SR-1's form is defined over JSON and not over one type: a binding, a grant
+ * payload and a fixture all need the same bytes.
+ *
+ * **Numbers, and the one place this is stricter than RFC 8785.** The shortest
+ * round-trip decimal for a value is what JavaScript's `Number#toString` produces,
+ * and that is the form RFC 8785 (JSON Canonicalization Scheme) adopts wholesale —
+ * exponent notation included, so `1e21` serializes as `1e+21`. This writer instead
+ * writes every number **positionally**: `1000000000000000000000`, and `1e-7` as
+ * `0.0000001`. The digits are the same digits; only the decimal point moves, so the
+ * value denoted is identical and it parses back to the identical double. What is
+ * bought is that a second implementation — in .NET, in Go, in a database function —
+ * has to agree about *digits*, not about ECMAScript's exponent thresholds and its
+ * `e+21` spelling, which is the part of RFC 8785 that needs an appendix. What is
+ * paid is length: a denormal near `5e-324` writes out as roughly a thousand
+ * characters. That is a bad number to have in an audit record for reasons that have
+ * nothing to do with this function.
+ *
+ * "Positionally" means the **shortest round-trip digits** with the point moved, not
+ * the double's exact binary value: `1.2345678901234569e23` is written
+ * `123456789012345690000000`, not the exact `123456789012345685803008`. The two
+ * parse to the same double, and SR-1 asks for the shortest round-trip form — so the
+ * digits are the ones `Number#toString` chose, and nothing else.
+ *
+ * @throws RangeError on `NaN` or an infinity — a number with no decimal form at all.
+ * @throws TypeError on a value with no canonical form (see the module header).
+ */
+export declare function canonicalJson(value: unknown): string;
+//# sourceMappingURL=canonical.d.ts.map

package/dist/model/canonical.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"canonical.d.ts","sourceRoot":"","sources":["../../src/model/canonical.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+GG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAEtD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAEtD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAChD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AASnD;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,cAAc;IAC7B,kEAAkE;IAClE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,4DAA4D;IAC5D,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;IACzB,wEAAwE;IACxE,QAAQ,CAAC,UAAU,CAAC,EAAE,OAAO,CAAC;CAC/B;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,cAAc;IAC7B,iEAAiE;IACjE,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,cAAc,EAAE,CAAC;IAC5C;;;;;;;;;OASG;IACH,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;CACnC;AAED,2FAA2F;AAC3F,MAAM,WAAW,mBAAmB;IAClC;;;;;OAKG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,WAAW,CAAC;CACpC;AAMD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,wBAAgB,2BAA2B,CACzC,SAAS,EAAE,cAAc,EACzB,UAAU,EAAE,YAAY,EACxB,GAAG,EAAE,WAAW,GACf,cAAc,CAsEhB;AAiFD;;;;;;;;;;;GAWG;AACH,wBAAgB,YAAY,CAC1B,SAAS,EAAE,cAAc,EACzB,UAAU,CAAC,EAAE,YAAY,GAAG,IAAI,EAChC,OAAO,CAAC,EAAE,mBAAmB,GAC5B,UAAU,CAEZ;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAC7B,SAAS,EAAE,cAAc,EACzB,UAAU,CAAC,EAAE,YAAY,GAAG,IAAI,EAChC,OAAO,CAAC,EAAE,mBAAmB,GAC5B,MAAM,CAER;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,aAAa,CACjC,SAAS,EAAE,cAAc,EACzB,UAAU,CAAC,EAAE,YAAY,GAAG,IAAI,EAChC,OAAO,CAAC,EAAE,mBAAmB,GAC5B,OAAO,CAAC,MAAM,CAAC,CAEjB;AAMD;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,WAAW,GAAG,SAAS,CAE9D;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,WAAW,GAAG,UAAU,CAEhE;AAED,4GAA4G;AAC5G,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,WAAW,GAAG,MAAM,CAE/D;AAED,mFAAmF;AACnF,wBAAsB,kBAAkB,CAAC,KAAK,EAAE,WAAW,GAAG,OAAO,CAAC,MAAM,CAAC,CAE5E;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,SAAS,CAAC,KAAK,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CAmBlE;AA0BD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAIpD"}