@datumesh/verify 0.1.1 → 0.2.1

package/dist/esm/json.js

@@ -4,11 +4,33 @@ import { fail } from './errors.js';
 import { hasLoneSurrogate } from './unicode.js';
 import { utf8Decode } from './utf8.js';
 /**
- * Nesting deeper than this is rejected with E_PARSE_JSON. SPEC.md sets no depth limit; this is
- * an implementation limit (Datumesh objects nest at most five levels) that keeps parsing and
- * canonicalisation from exhausting the call stack.
+ * SPEC 6.1: at most 64 levels of nesting ([ and { open at once, counted outside strings), checked
+ * before anything else in the text. Datumesh objects nest at most five levels.
  */
-export const MAX_DEPTH = 1000;
+export const MAX_DEPTH = 64;
+/** SPEC 6.1 order step 3: true when more than MAX_DEPTH brackets are open at once. */
+function tooDeep(s) {
+    let depth = 0;
+    let inString = false;
+    for (let i = 0; i < s.length; i++) {
+        const c = s.charCodeAt(i);
+        if (inString) {
+            if (c === 0x5c)
+                i++; // skip the escaped character
+            else if (c === 0x22)
+                inString = false;
+        }
+        else if (c === 0x22)
+            inString = true;
+        else if (c === 0x5b || c === 0x7b) {
+            if (++depth > MAX_DEPTH)
+                return true;
+        }
+        else if (c === 0x5d || c === 0x7d)
+            depth--;
+    }
+    return false;
+}
 export function isObject(v) {
     return typeof v === 'object' && v !== null && !Array.isArray(v);
 }
@@ -26,8 +48,11 @@ export function memberPath(path, name) {
     return /^[A-Za-z_][A-Za-z0-9_]*$/.test(name) ? `${path}.${name}` : `${path}[${JSON.stringify(name)}]`;
 }
 class Parser {
-    constructor(s) {
+    constructor(s, 
+    /** When given, receives the source text of every number, by JSON path. */
+    numbers) {
         this.s = s;
+        this.numbers = numbers;
         this.i = 0;
         /** Path of the first string holding an escaped lone surrogate; reported after parsing. */
         this.surrogatePath = null;
@@ -55,7 +80,7 @@ class Parser {
     }
     value(path, depth) {
         if (depth > MAX_DEPTH)
-            this.err(`nesting deeper than ${MAX_DEPTH} levels (implementation limit)`);
+            this.err(`nesting deeper than ${MAX_DEPTH} levels`); // tooDeep found it first
         const s = this.s;
         const c = s[this.i];
         if (c === '{')
@@ -77,7 +102,7 @@ class Parser {
             return null;
         }
         if (c === '-' || (c >= '0' && c <= '9'))
-            return this.number();
+            return this.number(path);
         if (c === undefined)
             this.err('unexpected end of input');
         if (s.startsWith('NaN', this.i) || s.startsWith('Infinity', this.i) || s.startsWith('-Infinity', this.i)) {
@@ -219,7 +244,7 @@ class Parser {
             this.surrogatePath = path;
         return out;
     }
-    number() {
+    number(path) {
         const s = this.s;
         const m = /-?(?:0|[1-9][0-9]*)(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?/y;
         m.lastIndex = this.i;
@@ -235,30 +260,35 @@ class Parser {
         const n = Number(text);
         if (!Number.isFinite(n))
             fail('E_PARSE_JSON', `number out of IEEE 754 range: ${text.slice(0, 40)}`, '$');
+        this.numbers?.set(path, text);
         return n;
     }
 }
 /** Parse JSON text strictly. */
-export function parseJsonText(text) {
+export function parseJsonText(text, numbers) {
+    // SPEC 6.1 order: BOM, (invalid UTF-8: parseJsonBytes), nesting, the first of syntax / NaN /
+    // overflow / duplicate in text order, then lone surrogates.
     if (text.charCodeAt(0) === 0xfeff)
         fail('E_PARSE_JSON', 'byte order mark', '$');
+    if (tooDeep(text))
+        fail('E_PARSE_JSON', `nesting deeper than ${MAX_DEPTH} levels`, '$');
+    const p = new Parser(text, numbers);
+    const v = p.parseDocument();
     if (hasLoneSurrogate(text))
         fail('E_PARSE_JSON', 'lone surrogate in the text', '$');
-    const p = new Parser(text);
-    const v = p.parseDocument();
     if (p.surrogatePath !== null)
         fail('E_PARSE_JSON', 'lone surrogate', p.surrogatePath);
     return v;
 }
 /** Parse UTF-8 JSON bytes strictly: no BOM, no invalid UTF-8. */
-export function parseJsonBytes(bytes) {
+export function parseJsonBytes(bytes, numbers) {
     if (bytes.length >= 3 && bytes[0] === 0xef && bytes[1] === 0xbb && bytes[2] === 0xbf) {
         fail('E_PARSE_JSON', 'byte order mark', '$');
     }
     const text = utf8Decode(bytes);
     if (text === null)
         fail('E_PARSE_JSON', 'invalid UTF-8', '$');
-    return parseJsonText(text);
+    return parseJsonText(text, numbers);
 }
 /**
  * Check an already-parsed JavaScript value against the JSON data model and return a private
@@ -267,7 +297,8 @@ export function parseJsonBytes(bytes) {
  * or bytes for that.
  */
 export function normalizeValue(v, path = '$', depth = 0) {
-    if (depth > MAX_DEPTH)
+    const container = typeof v === 'object' && v !== null;
+    if (container && depth >= MAX_DEPTH)
         fail('E_PARSE_JSON', `nesting deeper than ${MAX_DEPTH} levels (or a cycle)`, path);
     if (v === null || typeof v === 'boolean')
         return v;
@@ -298,12 +329,12 @@ export function normalizeValue(v, path = '$', depth = 0) {
     fail('E_PARSE_JSON', `${typeof v} is not a JSON value`, path);
 }
 /** JSON text (string), UTF-8 bytes (Uint8Array) or an already-parsed value. */
-export function toJson(input) {
+export function toJson(input, numbers) {
     if (typeof input === 'string')
-        return parseJsonText(input);
+        return parseJsonText(input, numbers);
     if (input instanceof Uint8Array)
-        return parseJsonBytes(input);
+        return parseJsonBytes(input, numbers);
     if (input instanceof ArrayBuffer)
-        return parseJsonBytes(new Uint8Array(input));
+        return parseJsonBytes(new Uint8Array(input), numbers);
     return normalizeValue(input);
 }

package/dist/esm/keys.d.ts

@@ -34,6 +34,8 @@ export declare function keysFromResponse(host: string, status: number | null, bo
 export declare function keysFromDocument(doc: unknown): KeysResult;
 /** Default timeout of fetchKeys, in milliseconds. */
 export declare const FETCH_TIMEOUT_MS = 10000;
+/** fetchKeys abandons a key document larger than this (SPEC 9.3: SHOULD bound retrieval). */
+export declare const FETCH_MAX_BYTES: number;
 /**
  * Fetch https://<host>/.well-known/datumesh.json once, with TLS verified by the platform, no
  * redirects followed and a timeout, then interpret it with keysFromResponse. The only function

package/dist/esm/keys.js

@@ -3,6 +3,15 @@ import { DatumeshError } from './errors.js';
 import { fromHex, keyIdOf } from './hash.js';
 import { has, isObject, memberPath, sortedKeys, toJson } from './json.js';
 import { LIMITS, checkDnsName, isHex, isInstant } from './lexical.js';
+function isDnsName(s) {
+    try {
+        checkDnsName(s, '$');
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
 class KeyDocError extends Error {
     constructor(msg, path) {
         super(msg);
@@ -24,6 +33,9 @@ function validateKeyDocument(doc, host) {
             bad(`missing member ${JSON.stringify(k)}`, '$');
     if (doc.proto !== 'datumesh/1')
         bad("proto must be 'datumesh/1'", '$.proto');
+    // 9.2 / 9.3: `host` is a DNS name (2.1); a document for any other host cannot satisfy 9.2.
+    if (typeof doc.host !== 'string' || !isDnsName(doc.host))
+        bad('host must be a DNS name (SPEC 2.1); keys are resolved only for DNS names', '$.host');
     if (doc.host !== host)
         bad(`host must be ${JSON.stringify(host)}`, '$.host');
     const keys = doc.keys;
@@ -126,6 +138,45 @@ export function keysFromDocument(doc) {
 }
 /** Default timeout of fetchKeys, in milliseconds. */
 export const FETCH_TIMEOUT_MS = 10000;
+/** fetchKeys abandons a key document larger than this (SPEC 9.3: SHOULD bound retrieval). */
+export const FETCH_MAX_BYTES = 256 * 1024;
+class TooLarge extends Error {
+}
+/** Read a response body, abandoning it once it exceeds FETCH_MAX_BYTES. */
+async function readBounded(res) {
+    const reader = res.body && typeof res.body.getReader === 'function' ? res.body.getReader() : null;
+    if (!reader) {
+        const b = new Uint8Array(await res.arrayBuffer());
+        if (b.length > FETCH_MAX_BYTES)
+            throw new TooLarge();
+        return b;
+    }
+    const parts = [];
+    let n = 0;
+    for (;;) {
+        const { done, value } = await reader.read();
+        if (done)
+            break;
+        n += value.length;
+        if (n > FETCH_MAX_BYTES) {
+            try {
+                await reader.cancel();
+            }
+            catch {
+                // abandoned anyway
+            }
+            throw new TooLarge();
+        }
+        parts.push(value);
+    }
+    const out = new Uint8Array(n);
+    let o = 0;
+    for (const p of parts) {
+        out.set(p, o);
+        o += p.length;
+    }
+    return out;
+}
 /**
  * Fetch https://<host>/.well-known/datumesh.json once, with TLS verified by the platform, no
  * redirects followed and a timeout, then interpret it with keysFromResponse. The only function
@@ -157,9 +208,11 @@ export async function fetchKeys(host, timeoutMs = FETCH_TIMEOUT_MS) {
             status = 0;
         if (status !== 200)
             return keysFromResponse(host, status);
-        body = new Uint8Array(await res.arrayBuffer());
+        body = await readBounded(res);
     }
     catch (e) {
+        if (e instanceof TooLarge)
+            return { ok: false, code: 'E_KEY_UNAVAILABLE', host, detail: `key document larger than 256 KiB; retrieval abandoned` };
         return { ok: false, code: 'E_KEY_UNAVAILABLE', host, detail: `retrieval failed: ${e instanceof Error ? e.message : String(e)}` };
     }
     return keysFromResponse(host, status, body);

package/dist/esm/lexical.d.ts

@@ -11,7 +11,7 @@ export declare const LIMITS: {
     readonly licence_url: 512;
     readonly keys: 64;
 };
-export declare const TYPES: readonly ["boolean", "date", "instant", "number", "string"];
+export declare const TYPES: readonly ["blob", "boolean", "date", "instant", "number", "string"];
 export type TypeName = (typeof TYPES)[number];
 export declare const VALID_TIME_TYPES: readonly string[];
 export declare function isTypeName(t: unknown): t is TypeName;
@@ -32,6 +32,8 @@ export declare function checkKeyRef(s: string, path: string): {
     host: string;
     id: string;
 };
+/** SPEC 3.1: a canonical decimal of at most 128 characters. */
+export declare function isNumber(s: string): boolean;
 /** SPEC 3.1. Grammar (E_CANON_NUMBER) before the 128-character limit (E_CANON_LIMIT). */
 export declare function checkNumber(s: string, path: string): void;
 export declare function isDate(s: string): boolean;
@@ -48,6 +50,14 @@ export declare function checkString(s: string, path: string, opts?: {
     body?: boolean;
     limit?: number;
 }): void;
+export declare const MEDIA_TYPE_MAX = 128;
+/** SPEC 3.7. Grammar, then length <= 2^53 - 1, then media type <= 128 characters; all E_CANON_BLOB. */
+export declare function checkBlob(s: string, path: string): {
+    sha256: string;
+    length: number;
+    mediaType: string;
+};
+export declare const URL_RE: RegExp;
 /**
  * SPEC 8.1 `licence`: an SPDX licence identifier or an https:// URL. SPEC.md gives no grammar;
  * this follows schemas/receipt.schema.json (and the reference tool): an identifier matches

package/dist/esm/lexical.js

@@ -17,7 +17,7 @@ export const LIMITS = {
     licence_url: 512,
     keys: 64,
 };
-export const TYPES = ['boolean', 'date', 'instant', 'number', 'string'];
+export const TYPES = ['blob', 'boolean', 'date', 'instant', 'number', 'string'];
 export const VALID_TIME_TYPES = ['date', 'instant', 'string'];
 export function isTypeName(t) {
     return typeof t === 'string' && TYPES.includes(t);
@@ -87,6 +87,10 @@ export function checkKeyRef(s, path) {
     return { host, id };
 }
 const NUMBER_RE = /^-?(?:0|[1-9][0-9]*)(?:\.[0-9]*[1-9])?$/;
+/** SPEC 3.1: a canonical decimal of at most 128 characters. */
+export function isNumber(s) {
+    return NUMBER_RE.test(s) && s !== '-0' && s.length <= LIMITS.number;
+}
 /** SPEC 3.1. Grammar (E_CANON_NUMBER) before the 128-character limit (E_CANON_LIMIT). */
 export function checkNumber(s, path) {
     if (!NUMBER_RE.test(s) || s === '-0')
@@ -146,8 +150,24 @@ export function checkString(s, path, opts = {}) {
 function hex4(cp) {
     return cp.toString(16).toUpperCase().padStart(4, '0');
 }
+// SPEC 3.7: <sha256>:<length>:<type>/<subtype>, with RFC 6838 restricted names in lowercase.
+const BLOB_RE = /^[0-9a-f]{64}:(0|[1-9][0-9]*):([a-z0-9][a-z0-9!#$&^_.+-]*\/[a-z0-9][a-z0-9!#$&^_.+-]*)$/;
+const MAX_SAFE = '9007199254740991';
+export const MEDIA_TYPE_MAX = 128;
+/** SPEC 3.7. Grammar, then length <= 2^53 - 1, then media type <= 128 characters; all E_CANON_BLOB. */
+export function checkBlob(s, path) {
+    const m = BLOB_RE.exec(s);
+    if (!m)
+        fail('E_CANON_BLOB', `not <sha256>:<length>:<type/subtype>: ${JSON.stringify(s)}`, path);
+    const len = m[1];
+    if (len.length > MAX_SAFE.length || (len.length === MAX_SAFE.length && len > MAX_SAFE))
+        fail('E_CANON_BLOB', `length above ${MAX_SAFE}`, path);
+    if (m[2].length > MEDIA_TYPE_MAX)
+        fail('E_CANON_BLOB', `media type longer than ${MEDIA_TYPE_MAX} characters`, path);
+    return { sha256: s.slice(0, 64), length: Number(len), mediaType: m[2] };
+}
 const SPDX_RE = /^[A-Za-z0-9][A-Za-z0-9.+-]*$/;
-const URL_RE = /^https:\/\/[!-~]+$/;
+export const URL_RE = /^https:\/\/[!-~]+$/;
 /**
  * SPEC 8.1 `licence`: an SPDX licence identifier or an https:// URL. SPEC.md gives no grammar;
  * this follows schemas/receipt.schema.json (and the reference tool): an identifier matches
@@ -182,6 +202,8 @@ export function checkTypedValue(type, value, path) {
         checkDate(value, path);
     else if (type === 'instant')
         checkInstant(value, path);
+    else if (type === 'blob')
+        checkBlob(value, path);
     else
         checkString(value, path);
 }

package/dist/esm/units-data.d.ts

@@ -0,0 +1,4 @@
+/** Literal units by group, in units.md order. Index units (units.md 2.4) are a pattern. */
+export declare const UNIT_GROUPS: {
+    readonly [group: string]: readonly string[];
+};

package/dist/esm/units-data.js

@@ -0,0 +1,8 @@
+// GENERATED by tools/gen-units.mjs from spec/units.md (the `units-…` fenced blocks).
+// Do not edit by hand; test/units.test.mjs checks that this file matches units.md.
+/** Literal units by group, in units.md order. Index units (units.md 2.4) are a pattern. */
+export const UNIT_GROUPS = {
+    currency: ["AED", "AFN", "ALL", "AMD", "AOA", "ARS", "AUD", "AWG", "AZN", "BAM", "BBD", "BDT", "BHD", "BIF", "BMD", "BND", "BOB", "BOV", "BRL", "BSD", "BTN", "BWP", "BYN", "BZD", "CAD", "CDF", "CHE", "CHF", "CHW", "CLF", "CLP", "CNY", "COP", "COU", "CRC", "CUP", "CVE", "CZK", "DJF", "DKK", "DOP", "DZD", "EGP", "ERN", "ETB", "EUR", "FJD", "FKP", "GBP", "GEL", "GHS", "GIP", "GMD", "GNF", "GTQ", "GYD", "HKD", "HNL", "HTG", "HUF", "IDR", "ILS", "INR", "IQD", "IRR", "ISK", "JMD", "JOD", "JPY", "KES", "KGS", "KHR", "KMF", "KPW", "KRW", "KWD", "KYD", "KZT", "LAK", "LBP", "LKR", "LRD", "LSL", "LYD", "MAD", "MDL", "MGA", "MKD", "MMK", "MNT", "MOP", "MRU", "MUR", "MVR", "MWK", "MXN", "MXV", "MYR", "MZN", "NAD", "NGN", "NIO", "NOK", "NPR", "NZD", "OMR", "PAB", "PEN", "PGK", "PHP", "PKR", "PLN", "PYG", "QAR", "RON", "RSD", "RUB", "RWF", "SAR", "SBD", "SCR", "SDG", "SEK", "SGD", "SHP", "SLE", "SOS", "SRD", "SSP", "STN", "SVC", "SYP", "SZL", "THB", "TJS", "TMT", "TND", "TOP", "TRY", "TTD", "TWD", "TZS", "UAH", "UGX", "USD", "USN", "UYI", "UYU", "UYW", "UZS", "VED", "VES", "VND", "VUV", "WST", "XAD", "XAF", "XAG", "XAU", "XBA", "XBB", "XBC", "XBD", "XCD", "XCG", "XDR", "XOF", "XPD", "XPF", "XPT", "XSU", "XTS", "XUA", "YER", "ZAR", "ZMW", "ZWG", "BGN", "CYP", "EEK", "GRD", "HRK", "LTL", "LVL", "MTL", "ROL", "SIT", "SKK", "TRL"],
+    physical: ["m", "kg", "s", "A", "K", "mol", "cd", "degC", "m/s", "W", "kWh", "mm", "cm", "km/h", "hPa", "W/m2"],
+    ratio: ["percent", "permille", "bp", "1", "count"],
+};

package/dist/esm/units.d.ts

@@ -0,0 +1,24 @@
+import { type JsonObject, type JsonValue } from './json.js';
+/** A currency code from units.md 2.1 (List One and the withdrawn codes). */
+export declare function isCurrency(s: unknown): boolean;
+/** units.md 2.4: index:<YYYY[-MM[-DD]]>=<number greater than 0>, at most 64 characters. */
+export declare function isIndexUnit(s: string): boolean;
+/** A literal unit (units.md section 2): a listed string or an index unit. Byte-for-byte. */
+export declare function isUnitLiteral(s: unknown): boolean;
+/**
+ * Step 2 for a unit: a string, {"arg": <string>}, or {"of": side, "per": side} where a side is
+ * a string or {"arg": <string>}. Anything else is E_SCHEMA (SPEC 7.1, units.md 1).
+ */
+export declare function structUnit(u: JsonValue, path: string): void;
+/**
+ * Step 3 for a unit whose shape passed structUnit. `args` is the signature's `args`: a
+ * reference must name one of them whose declared type is `string` (E_CANON_UNIT).
+ */
+export declare function canonUnit(u: JsonValue, args: JsonObject, path: string): void;
+/**
+ * units.md section 3: the unit of one cell's value, for a descriptor and a cell that have
+ * passed validation and whose fn_hash matches. `returns` is the signature's `returns`.
+ * A referenced argument must be bound (E_ARG_MISSING), not a slice (E_SLICE), of its declared
+ * type (E_ARG_TYPE), and a literal unit (E_CANON_UNIT); on a rate side, a currency.
+ */
+export declare function resolveUnit(returns: JsonValue, cellArgs: JsonObject, path: string, argsPath: string): string | null;

package/dist/esm/units.js

@@ -0,0 +1,123 @@
+// Units (SPEC.md 7.1, units.md): shapes in a signature (step 2, E_SCHEMA), validity against the
+// closed list (step 3, E_CANON_UNIT), and resolution of a cell's unit (units.md section 3).
+import { fail } from './errors.js';
+import { has, isObject, memberPath } from './json.js';
+import { isDate, isNumber } from './lexical.js';
+import { UNIT_GROUPS } from './units-data.js';
+const CURRENCY = new Set(UNIT_GROUPS.currency);
+const LITERAL = new Set(Object.values(UNIT_GROUPS).flat());
+const INDEX_RE = /^index:([0-9]{4}(?:-[0-9]{2}(?:-[0-9]{2})?)?)=(.*)$/;
+const INDEX_MAX = 64;
+/** A currency code from units.md 2.1 (List One and the withdrawn codes). */
+export function isCurrency(s) {
+    return typeof s === 'string' && CURRENCY.has(s);
+}
+/** units.md 2.4: index:<YYYY[-MM[-DD]]>=<number greater than 0>, at most 64 characters. */
+export function isIndexUnit(s) {
+    if (s.length > INDEX_MAX)
+        return false;
+    const m = INDEX_RE.exec(s);
+    if (!m)
+        return false;
+    const [y, mo = '01', d = '01'] = m[1].split('-');
+    if (!isDate(`${y}-${mo}-${d}`))
+        return false;
+    return isNumber(m[2]) && !m[2].startsWith('-') && m[2] !== '0';
+}
+/** A literal unit (units.md section 2): a listed string or an index unit. Byte-for-byte. */
+export function isUnitLiteral(s) {
+    return typeof s === 'string' && (LITERAL.has(s) || isIndexUnit(s));
+}
+const isRef = (u) => Object.keys(u).length === 1 && has(u, 'arg') && typeof u.arg === 'string';
+/**
+ * Step 2 for a unit: a string, {"arg": <string>}, or {"of": side, "per": side} where a side is
+ * a string or {"arg": <string>}. Anything else is E_SCHEMA (SPEC 7.1, units.md 1).
+ */
+export function structUnit(u, path) {
+    if (typeof u === 'string')
+        return;
+    if (isObject(u)) {
+        if (isRef(u))
+            return;
+        const keys = Object.keys(u);
+        if (keys.length === 2 && has(u, 'of') && has(u, 'per')) {
+            for (const side of ['of', 'per']) {
+                const v = u[side];
+                if (typeof v === 'string' || (isObject(v) && isRef(v)))
+                    continue;
+                fail('E_SCHEMA', 'a rate side is a currency code or {"arg": name}', memberPath(path, side));
+            }
+            return;
+        }
+    }
+    fail('E_SCHEMA', 'a unit is a string, {"arg": name} or {"of", "per"}', path);
+}
+/**
+ * Step 3 for a unit whose shape passed structUnit. `args` is the signature's `args`: a
+ * reference must name one of them whose declared type is `string` (E_CANON_UNIT).
+ */
+export function canonUnit(u, args, path) {
+    const checkRef = (r, p) => {
+        const name = r.arg;
+        const d = has(args, name) ? args[name] : null;
+        if (!isObject(d) || d.type !== 'string')
+            fail('E_CANON_UNIT', `a unit names a string argument of the signature: ${JSON.stringify(name)}`, p);
+    };
+    if (typeof u === 'string') {
+        if (!isUnitLiteral(u))
+            fail('E_CANON_UNIT', `not a unit listed in units.md: ${JSON.stringify(u)}`, path);
+        return;
+    }
+    const o = u;
+    if (has(o, 'arg'))
+        return checkRef(o, path);
+    for (const side of ['of', 'per']) {
+        const v = o[side];
+        const p = memberPath(path, side);
+        if (typeof v === 'string') {
+            if (!isCurrency(v))
+                fail('E_CANON_UNIT', `a rate side is a currency code: ${JSON.stringify(v)}`, p);
+        }
+        else
+            checkRef(v, p);
+    }
+}
+/**
+ * units.md section 3: the unit of one cell's value, for a descriptor and a cell that have
+ * passed validation and whose fn_hash matches. `returns` is the signature's `returns`.
+ * A referenced argument must be bound (E_ARG_MISSING), not a slice (E_SLICE), of its declared
+ * type (E_ARG_TYPE), and a literal unit (E_CANON_UNIT); on a rate side, a currency.
+ */
+export function resolveUnit(returns, cellArgs, path, argsPath) {
+    if (!isObject(returns))
+        return null; // only a number return is an object, and only it has a unit
+    const u = returns.unit;
+    const side = (v, p, currency) => {
+        if (typeof v === 'string')
+            return v; // a literal, already checked by canonUnit
+        const name = v.arg;
+        const ap = memberPath(argsPath, name);
+        if (!has(cellArgs, name))
+            fail('E_ARG_MISSING', `the cell does not bind ${JSON.stringify(name)}`, argsPath);
+        const a = cellArgs[name];
+        if (a === '*')
+            fail('E_SLICE', `${name} is a slice; its unit is not one string`, ap);
+        const scalar = a;
+        if (scalar.type !== 'string')
+            fail('E_ARG_TYPE', `${name} is declared string`, ap);
+        const value = scalar.value;
+        if (currency ? !isCurrency(value) : !isUnitLiteral(value)) {
+            fail('E_CANON_UNIT', `argument ${name} is not ${currency ? 'a currency code' : 'a unit'}: ${JSON.stringify(value)}`, p);
+        }
+        return value;
+    };
+    const p = memberPath(path, 'unit');
+    if (typeof u === 'string')
+        return u;
+    const o = u;
+    if (has(o, 'arg'))
+        return side(o, p, false);
+    const of = side(o.of, memberPath(p, 'of'), true);
+    const per = side(o.per, memberPath(p, 'per'), true);
+    return `${of}/${per}`;
+}

package/dist/esm/uri.d.ts

@@ -11,13 +11,25 @@ export interface CellRef {
     ns: string;
     asof?: string;
 }
-/** A function descriptor's `signature` member (SPEC 7). */
+/** A unit in a signature (SPEC 7.1): a literal from units.md, an argument reference, or a rate. */
+export type UnitRef = {
+    arg: string;
+};
+export type Unit = string | UnitRef | {
+    of: string | UnitRef;
+    per: string | UnitRef;
+};
+/** A function descriptor's `signature` member (SPEC 7). Numbers declare a unit. */
 export interface Signature {
     args: Record<string, {
         type: TypeName;
         valid: boolean;
+        unit?: Unit;
     }>;
-    returns: TypeName;
+    returns: Exclude<TypeName, 'number'> | {
+        type: 'number';
+        unit: Unit;
+    };
 }
 /**
  * Parse a cell URI into a cell reference, taking argument types from the function's

package/dist/esm/uri.js

@@ -1,9 +1,9 @@
 // Cell URIs (SPEC.md section 5).
-import { DatumeshError, fail } from './errors.js';
-import { isObject, sortedKeys, toJson } from './json.js';
-import { LIMITS, checkArgName, checkInstant, checkName, checkNamespace, checkTypedValue } from './lexical.js';
+import { fail } from './errors.js';
+import { isObject, memberPath, normalizeValue, sortedKeys, toJson } from './json.js';
+import { LIMITS, checkArgName, checkDnsName, checkInstant, checkName, checkNamespace, checkTypedValue, isTypeName } from './lexical.js';
 import { utf8Decode, utf8Encode } from './utf8.js';
-import { canonSignature, structSignature, validate } from './validate.js';
+import { validate } from './validate.js';
 const SCHEME = 'cell://';
 function isLiteral(c) {
     return /^[A-Za-z0-9\-._~:]$/.test(c);
@@ -44,19 +44,29 @@ function encodeValue(s) {
     }
     return out;
 }
+/**
+ * SPEC 5.4 step 5: the signature is taken as given (it comes from a descriptor already checked
+ * under section 7), but it must be readable: an object with an `args` object whose members are
+ * objects with a string `type` (E_SCHEMA otherwise, in JCS order of names). Nothing else in it is
+ * examined; an unknown type name fails only when a value of that argument is read (step 6).
+ */
 function readSignature(signature) {
-    if (signature === null || signature === undefined)
-        throw new TypeError('parseUri needs the function signature (descriptor.signature)');
     let sig;
     try {
-        sig = toJson(signature);
-        structSignature(sig, 'signature');
-        canonSignature(sig, 'signature');
+        sig = normalizeValue(signature, 'signature');
     }
-    catch (e) {
-        if (e instanceof DatumeshError)
-            throw new DatumeshError(e.code, `invalid signature: ${e.detail}`, e.path?.replace(/^\$/, 'signature') ?? 'signature');
-        throw e;
+    catch {
+        fail('E_SCHEMA', 'the signature is not JSON data', 'signature');
+    }
+    if (!isObject(sig))
+        fail('E_SCHEMA', 'the signature is not an object', 'signature');
+    const args = sig.args;
+    if (!isObject(args))
+        fail('E_SCHEMA', 'the signature has no args object', 'signature.args');
+    for (const k of sortedKeys(args)) {
+        const d = args[k];
+        if (!isObject(d) || typeof d.type !== 'string')
+            fail('E_SCHEMA', `the declaration of ${JSON.stringify(k)} is not an object with a string type`, memberPath('signature.args', k));
     }
     return sig;
 }
@@ -68,8 +78,6 @@ function readSignature(signature) {
 export function parseUri(uri, signature) {
     if (typeof uri !== 'string')
         throw new TypeError('uri must be a string');
-    const sig = readSignature(signature);
-    const declared = sig.args;
     // 1. Outer grammar.
     if (!uri.startsWith(SCHEME) || uri.includes('#'))
         fail('E_PARSE_URI', 'not cell://<namespace>/<function>[?<query>] without fragment', '$');
@@ -79,8 +87,7 @@ export function parseUri(uri, signature) {
     const query = q < 0 ? null : rest.slice(q + 1);
     if (query === '')
         fail('E_PARSE_URI', 'empty query', '$');
-    // SPEC 5.1 lists userinfo and a port among outer-grammar failures (E_PARSE_URI). (The
-    // reference tool reports them as E_CANON_NAME; see DEFECTS.md.)
+    // SPEC 5.1: an @ or : in the authority is userinfo or a port (E_PARSE_URI).
     const authority = path.split('/')[0];
     if (authority.includes('@'))
         fail('E_PARSE_URI', 'a cell URI has no userinfo', '$');
@@ -129,7 +136,9 @@ export function parseUri(uri, signature) {
     // 4. Argument count.
     if (argParams.length > LIMITS.args)
         fail('E_CANON_LIMIT', `more than ${LIMITS.args} arguments`, 'uri.query');
-    // 5. Against the signature: unknown arguments, then missing ones.
+    // 5. The signature (readable, E_SCHEMA), then the arguments against it: unknown arguments,
+    // then missing ones.
+    const declared = readSignature(signature).args;
     for (const p of argParams) {
         if (!Object.prototype.hasOwnProperty.call(declared, p.name))
             fail('E_ARG_UNKNOWN', `function declares no argument ${JSON.stringify(p.name)}`, at(p.name));
@@ -148,6 +157,8 @@ export function parseUri(uri, signature) {
         }
         const type = declared[p.name].type;
         const s = decodeValue(p.value, at(p.name));
+        if (!isTypeName(type))
+            fail('E_CANON_TYPE', `unknown type ${JSON.stringify(type)} in the signature`, `signature.args.${p.name}.type`);
         if (type === 'boolean') {
             if (s !== 'true' && s !== 'false')
                 fail('E_CANON_TYPE', 'boolean must be true or false', at(p.name));
@@ -192,5 +203,7 @@ export function formatUri(ref) {
 export function httpsUrl(uri, mesh) {
     if (!uri.startsWith(SCHEME))
         fail('E_PARSE_URI', 'not a cell URI', '$');
+    // SPEC 5.3: the mesh is a DNS name on the default HTTPS port (no port, IP address or userinfo).
+    checkDnsName(mesh, 'mesh');
     return `https://${mesh}/cell/${uri.slice(SCHEME.length)}`;
 }

package/dist/esm/validate.d.ts

@@ -3,8 +3,16 @@ export type Kind = 'scalar' | 'cell' | 'ref' | 'function' | 'receipt' | 'jcs';
 export declare const KINDS: readonly Kind[];
 export declare function structSignature(v: JsonValue, path: string): void;
 export declare function canonSignature(sig: JsonObject, path: string): void;
+/** The return type named by a valid signature's `returns` (SPEC 10.1 step 7.4). */
+export declare function returnType(sig: JsonObject): string;
 /** Validate `v` as `kind` (steps 2-3; for receipts also step 4). Throws DatumeshError. */
 export declare function validate(v: JsonValue, kind: Kind, path?: string): void;
+/**
+ * The unit of a cell's value (SPEC 7.1, units.md 3). Order: the cell (structure, canonical
+ * form), fn_hash against the descriptor (E_FN_HASH_MISMATCH), the descriptor (structure,
+ * canonical form), then substitution.
+ */
+export declare function cellUnit(desc: JsonValue, cell: JsonValue, fnHash: (d: JsonValue) => string): string | null;
 /** Receipt step 2 only: true when the receipt has the right members and JSON types. */
 export declare function receiptStructure(v: JsonValue): void;
 /** Receipt steps 3 and 4, after receiptStructure has passed. */