@datumesh/verify 0.1.1 → 0.2.1

package/dist/cjs/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/cjs/keys.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.FETCH_TIMEOUT_MS = void 0;
+exports.FETCH_MAX_BYTES = exports.FETCH_TIMEOUT_MS = void 0;
 exports.keysFromResponse = keysFromResponse;
 exports.keysFromDocument = keysFromDocument;
 exports.fetchKeys = fetchKeys;
@@ -11,6 +11,15 @@ const errors_js_1 = require("./errors.js");
 const hash_js_1 = require("./hash.js");
 const json_js_1 = require("./json.js");
 const lexical_js_1 = require("./lexical.js");
+function isDnsName(s) {
+    try {
+        (0, lexical_js_1.checkDnsName)(s, '$');
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
 class KeyDocError extends Error {
     constructor(msg, path) {
         super(msg);
@@ -32,6 +41,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;
@@ -134,6 +146,45 @@ function keysFromDocument(doc) {
 }
 /** Default timeout of fetchKeys, in milliseconds. */
 exports.FETCH_TIMEOUT_MS = 10000;
+/** fetchKeys abandons a key document larger than this (SPEC 9.3: SHOULD bound retrieval). */
+exports.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 > exports.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 > exports.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
@@ -165,9 +216,11 @@ async function fetchKeys(host, timeoutMs = exports.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/cjs/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/cjs/lexical.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.VALID_TIME_TYPES = exports.TYPES = exports.LIMITS = void 0;
+exports.URL_RE = exports.MEDIA_TYPE_MAX = exports.VALID_TIME_TYPES = exports.TYPES = exports.LIMITS = void 0;
 exports.isTypeName = isTypeName;
 exports.checkName = checkName;
 exports.checkArgName = checkArgName;
@@ -10,12 +10,14 @@ exports.checkFunctionName = checkFunctionName;
 exports.isHex = isHex;
 exports.checkHex = checkHex;
 exports.checkKeyRef = checkKeyRef;
+exports.isNumber = isNumber;
 exports.checkNumber = checkNumber;
 exports.isDate = isDate;
 exports.isInstant = isInstant;
 exports.checkDate = checkDate;
 exports.checkInstant = checkInstant;
 exports.checkString = checkString;
+exports.checkBlob = checkBlob;
 exports.checkLicence = checkLicence;
 exports.checkTypedValue = checkTypedValue;
 // Lexical rules of SPEC.md sections 2-3 and 8.1. Each check throws a DatumeshError with the
@@ -37,7 +39,7 @@ exports.LIMITS = {
     licence_url: 512,
     keys: 64,
 };
-exports.TYPES = ['boolean', 'date', 'instant', 'number', 'string'];
+exports.TYPES = ['blob', 'boolean', 'date', 'instant', 'number', 'string'];
 exports.VALID_TIME_TYPES = ['date', 'instant', 'string'];
 function isTypeName(t) {
     return typeof t === 'string' && exports.TYPES.includes(t);
@@ -107,6 +109,10 @@ 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. */
+function isNumber(s) {
+    return NUMBER_RE.test(s) && s !== '-0' && s.length <= exports.LIMITS.number;
+}
 /** SPEC 3.1. Grammar (E_CANON_NUMBER) before the 128-character limit (E_CANON_LIMIT). */
 function checkNumber(s, path) {
     if (!NUMBER_RE.test(s) || s === '-0')
@@ -166,8 +172,24 @@ 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';
+exports.MEDIA_TYPE_MAX = 128;
+/** SPEC 3.7. Grammar, then length <= 2^53 - 1, then media type <= 128 characters; all E_CANON_BLOB. */
+function checkBlob(s, path) {
+    const m = BLOB_RE.exec(s);
+    if (!m)
+        (0, errors_js_1.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))
+        (0, errors_js_1.fail)('E_CANON_BLOB', `length above ${MAX_SAFE}`, path);
+    if (m[2].length > exports.MEDIA_TYPE_MAX)
+        (0, errors_js_1.fail)('E_CANON_BLOB', `media type longer than ${exports.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:\/\/[!-~]+$/;
+exports.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
@@ -176,7 +198,7 @@ const URL_RE = /^https:\/\/[!-~]+$/;
  */
 function checkLicence(s, path) {
     if (s.startsWith('https://')) {
-        if (!URL_RE.test(s))
+        if (!exports.URL_RE.test(s))
             (0, errors_js_1.fail)('E_CANON_LICENCE', 'licence URL has characters outside printable ASCII', path);
         if (s.length > exports.LIMITS.licence_url)
             (0, errors_js_1.fail)('E_CANON_LIMIT', 'licence URL too long', path);
@@ -202,6 +224,8 @@ 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/cjs/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/cjs/units-data.js

@@ -0,0 +1,11 @@
+"use strict";
+// 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.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UNIT_GROUPS = void 0;
+/** Literal units by group, in units.md order. Index units (units.md 2.4) are a pattern. */
+exports.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/cjs/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/cjs/units.js

@@ -0,0 +1,131 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isCurrency = isCurrency;
+exports.isIndexUnit = isIndexUnit;
+exports.isUnitLiteral = isUnitLiteral;
+exports.structUnit = structUnit;
+exports.canonUnit = canonUnit;
+exports.resolveUnit = resolveUnit;
+// 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).
+const errors_js_1 = require("./errors.js");
+const json_js_1 = require("./json.js");
+const lexical_js_1 = require("./lexical.js");
+const units_data_js_1 = require("./units-data.js");
+const CURRENCY = new Set(units_data_js_1.UNIT_GROUPS.currency);
+const LITERAL = new Set(Object.values(units_data_js_1.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). */
+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. */
+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 (!(0, lexical_js_1.isDate)(`${y}-${mo}-${d}`))
+        return false;
+    return (0, lexical_js_1.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. */
+function isUnitLiteral(s) {
+    return typeof s === 'string' && (LITERAL.has(s) || isIndexUnit(s));
+}
+const isRef = (u) => Object.keys(u).length === 1 && (0, json_js_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).
+ */
+function structUnit(u, path) {
+    if (typeof u === 'string')
+        return;
+    if ((0, json_js_1.isObject)(u)) {
+        if (isRef(u))
+            return;
+        const keys = Object.keys(u);
+        if (keys.length === 2 && (0, json_js_1.has)(u, 'of') && (0, json_js_1.has)(u, 'per')) {
+            for (const side of ['of', 'per']) {
+                const v = u[side];
+                if (typeof v === 'string' || ((0, json_js_1.isObject)(v) && isRef(v)))
+                    continue;
+                (0, errors_js_1.fail)('E_SCHEMA', 'a rate side is a currency code or {"arg": name}', (0, json_js_1.memberPath)(path, side));
+            }
+            return;
+        }
+    }
+    (0, errors_js_1.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).
+ */
+function canonUnit(u, args, path) {
+    const checkRef = (r, p) => {
+        const name = r.arg;
+        const d = (0, json_js_1.has)(args, name) ? args[name] : null;
+        if (!(0, json_js_1.isObject)(d) || d.type !== 'string')
+            (0, errors_js_1.fail)('E_CANON_UNIT', `a unit names a string argument of the signature: ${JSON.stringify(name)}`, p);
+    };
+    if (typeof u === 'string') {
+        if (!isUnitLiteral(u))
+            (0, errors_js_1.fail)('E_CANON_UNIT', `not a unit listed in units.md: ${JSON.stringify(u)}`, path);
+        return;
+    }
+    const o = u;
+    if ((0, json_js_1.has)(o, 'arg'))
+        return checkRef(o, path);
+    for (const side of ['of', 'per']) {
+        const v = o[side];
+        const p = (0, json_js_1.memberPath)(path, side);
+        if (typeof v === 'string') {
+            if (!isCurrency(v))
+                (0, errors_js_1.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.
+ */
+function resolveUnit(returns, cellArgs, path, argsPath) {
+    if (!(0, json_js_1.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 = (0, json_js_1.memberPath)(argsPath, name);
+        if (!(0, json_js_1.has)(cellArgs, name))
+            (0, errors_js_1.fail)('E_ARG_MISSING', `the cell does not bind ${JSON.stringify(name)}`, argsPath);
+        const a = cellArgs[name];
+        if (a === '*')
+            (0, errors_js_1.fail)('E_SLICE', `${name} is a slice; its unit is not one string`, ap);
+        const scalar = a;
+        if (scalar.type !== 'string')
+            (0, errors_js_1.fail)('E_ARG_TYPE', `${name} is declared string`, ap);
+        const value = scalar.value;
+        if (currency ? !isCurrency(value) : !isUnitLiteral(value)) {
+            (0, errors_js_1.fail)('E_CANON_UNIT', `argument ${name} is not ${currency ? 'a currency code' : 'a unit'}: ${JSON.stringify(value)}`, p);
+        }
+        return value;
+    };
+    const p = (0, json_js_1.memberPath)(path, 'unit');
+    if (typeof u === 'string')
+        return u;
+    const o = u;
+    if ((0, json_js_1.has)(o, 'arg'))
+        return side(o, p, false);
+    const of = side(o.of, (0, json_js_1.memberPath)(p, 'of'), true);
+    const per = side(o.per, (0, json_js_1.memberPath)(p, 'per'), true);
+    return `${of}/${per}`;
+}

package/dist/cjs/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/cjs/uri.js

@@ -49,19 +49,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 = (0, json_js_1.toJson)(signature);
-        (0, validate_js_1.structSignature)(sig, 'signature');
-        (0, validate_js_1.canonSignature)(sig, 'signature');
+        sig = (0, json_js_1.normalizeValue)(signature, 'signature');
     }
-    catch (e) {
-        if (e instanceof errors_js_1.DatumeshError)
-            throw new errors_js_1.DatumeshError(e.code, `invalid signature: ${e.detail}`, e.path?.replace(/^\$/, 'signature') ?? 'signature');
-        throw e;
+    catch {
+        (0, errors_js_1.fail)('E_SCHEMA', 'the signature is not JSON data', 'signature');
+    }
+    if (!(0, json_js_1.isObject)(sig))
+        (0, errors_js_1.fail)('E_SCHEMA', 'the signature is not an object', 'signature');
+    const args = sig.args;
+    if (!(0, json_js_1.isObject)(args))
+        (0, errors_js_1.fail)('E_SCHEMA', 'the signature has no args object', 'signature.args');
+    for (const k of (0, json_js_1.sortedKeys)(args)) {
+        const d = args[k];
+        if (!(0, json_js_1.isObject)(d) || typeof d.type !== 'string')
+            (0, errors_js_1.fail)('E_SCHEMA', `the declaration of ${JSON.stringify(k)} is not an object with a string type`, (0, json_js_1.memberPath)('signature.args', k));
     }
     return sig;
 }
@@ -73,8 +83,6 @@ function readSignature(signature) {
 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('#'))
         (0, errors_js_1.fail)('E_PARSE_URI', 'not cell://<namespace>/<function>[?<query>] without fragment', '$');
@@ -84,8 +92,7 @@ function parseUri(uri, signature) {
     const query = q < 0 ? null : rest.slice(q + 1);
     if (query === '')
         (0, errors_js_1.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('@'))
         (0, errors_js_1.fail)('E_PARSE_URI', 'a cell URI has no userinfo', '$');
@@ -134,7 +141,9 @@ function parseUri(uri, signature) {
     // 4. Argument count.
     if (argParams.length > lexical_js_1.LIMITS.args)
         (0, errors_js_1.fail)('E_CANON_LIMIT', `more than ${lexical_js_1.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))
             (0, errors_js_1.fail)('E_ARG_UNKNOWN', `function declares no argument ${JSON.stringify(p.name)}`, at(p.name));
@@ -153,6 +162,8 @@ function parseUri(uri, signature) {
         }
         const type = declared[p.name].type;
         const s = decodeValue(p.value, at(p.name));
+        if (!(0, lexical_js_1.isTypeName)(type))
+            (0, errors_js_1.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')
                 (0, errors_js_1.fail)('E_CANON_TYPE', 'boolean must be true or false', at(p.name));
@@ -197,5 +208,7 @@ function formatUri(ref) {
 function httpsUrl(uri, mesh) {
     if (!uri.startsWith(SCHEME))
         (0, errors_js_1.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).
+    (0, lexical_js_1.checkDnsName)(mesh, 'mesh');
     return `https://${mesh}/cell/${uri.slice(SCHEME.length)}`;
 }

package/dist/cjs/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. */

package/dist/cjs/validate.js

@@ -3,7 +3,9 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.KINDS = void 0;
 exports.structSignature = structSignature;
 exports.canonSignature = canonSignature;
+exports.returnType = returnType;
 exports.validate = validate;
+exports.cellUnit = cellUnit;
 exports.receiptStructure = receiptStructure;
 exports.receiptCanonicalAndConsistent = receiptCanonicalAndConsistent;
 exports.inferKind = inferKind;
@@ -13,6 +15,7 @@ exports.inferKind = inferKind;
 const errors_js_1 = require("./errors.js");
 const json_js_1 = require("./json.js");
 const lexical_js_1 = require("./lexical.js");
+const units_js_1 = require("./units.js");
 exports.KINDS = ['scalar', 'cell', 'ref', 'function', 'receipt', 'jcs'];
 const SLICE = '*';
 // ---------------------------------------------------------------- step 2: structure
@@ -85,12 +88,24 @@ function structSignature(v, path) {
     for (const k of (0, json_js_1.sortedKeys)(args)) {
         const p = (0, json_js_1.memberPath)(argsPath, k);
         const d = expectObject(args[k], p);
-        members(d, ['type', 'valid'], [], p);
+        members(d, ['type', 'valid'], ['unit'], p);
         expectString(d, 'type', p);
+        if ((0, json_js_1.has)(d, 'unit'))
+            (0, units_js_1.structUnit)(d.unit, (0, json_js_1.memberPath)(p, 'unit'));
         if (typeof d.valid !== 'boolean')
             (0, errors_js_1.fail)('E_SCHEMA', 'valid must be a boolean', (0, json_js_1.memberPath)(p, 'valid'));
     }
-    expectString(sig, 'returns', path);
+    // SPEC 7: a type name, or {"type", "unit"} (the unit's absence is E_CANON_UNIT, in step 3).
+    const rp = (0, json_js_1.memberPath)(path, 'returns');
+    const r = sig.returns;
+    if (typeof r === 'string')
+        return;
+    if (!(0, json_js_1.isObject)(r))
+        (0, errors_js_1.fail)('E_SCHEMA', 'returns must be a type name or an object', rp);
+    members(r, ['type'], ['unit'], rp);
+    expectString(r, 'type', rp);
+    if ((0, json_js_1.has)(r, 'unit'))
+        (0, units_js_1.structUnit)(r.unit, (0, json_js_1.memberPath)(rp, 'unit'));
 }
 const RECEIPT_MEMBERS = [
     'asof',
@@ -194,14 +209,43 @@ function canonSignature(sig, path) {
         const p = (0, json_js_1.memberPath)(argsPath, k);
         (0, lexical_js_1.checkArgName)(k, p);
         const d = args[k];
+        // SPEC 7: type, then unit, then valid.
         if (!(0, lexical_js_1.isTypeName)(d.type))
             (0, errors_js_1.fail)('E_CANON_TYPE', `unknown type ${JSON.stringify(d.type)}`, (0, json_js_1.memberPath)(p, 'type'));
+        if (d.type === 'number') {
+            if (!(0, json_js_1.has)(d, 'unit'))
+                (0, errors_js_1.fail)('E_CANON_UNIT', 'a number argument declares its unit', p);
+            (0, units_js_1.canonUnit)(d.unit, args, (0, json_js_1.memberPath)(p, 'unit'));
+        }
+        else if ((0, json_js_1.has)(d, 'unit')) {
+            (0, errors_js_1.fail)('E_CANON_UNIT', 'only number arguments have a unit', (0, json_js_1.memberPath)(p, 'unit'));
+        }
         if (d.valid === true && !lexical_js_1.VALID_TIME_TYPES.includes(d.type)) {
             (0, errors_js_1.fail)('E_CANON_TYPE', 'a valid-time argument must be a date, instant or string', p);
         }
     }
-    if (!(0, lexical_js_1.isTypeName)(sig.returns))
-        (0, errors_js_1.fail)('E_CANON_TYPE', `unknown type ${JSON.stringify(sig.returns)}`, (0, json_js_1.memberPath)(path, 'returns'));
+    const rp = (0, json_js_1.memberPath)(path, 'returns');
+    const r = sig.returns;
+    if (typeof r === 'string') {
+        if (!(0, lexical_js_1.isTypeName)(r))
+            (0, errors_js_1.fail)('E_CANON_TYPE', `unknown type ${JSON.stringify(r)}`, rp);
+        if (r === 'number')
+            (0, errors_js_1.fail)('E_CANON_UNIT', 'a number return is {"type": "number", "unit": ...}, not the bare name', rp);
+        return;
+    }
+    const o = r;
+    if (!(0, lexical_js_1.isTypeName)(o.type))
+        (0, errors_js_1.fail)('E_CANON_TYPE', `unknown type ${JSON.stringify(o.type)}`, (0, json_js_1.memberPath)(rp, 'type'));
+    if (o.type !== 'number')
+        (0, errors_js_1.fail)('E_CANON_UNIT', 'only a number return is written as an object', rp);
+    if (!(0, json_js_1.has)(o, 'unit'))
+        (0, errors_js_1.fail)('E_CANON_UNIT', 'a number return declares its unit', rp);
+    (0, units_js_1.canonUnit)(o.unit, args, (0, json_js_1.memberPath)(rp, 'unit'));
+}
+/** The return type named by a valid signature's `returns` (SPEC 10.1 step 7.4). */
+function returnType(sig) {
+    const r = sig.returns;
+    return typeof r === 'string' ? r : r.type;
 }
 function canonFunction(o, path) {
     const code = o.code;
@@ -317,6 +361,21 @@ function validate(v, kind, path = '$') {
             return;
     }
 }
+/**
+ * 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.
+ */
+function cellUnit(desc, cell, fnHash) {
+    structCell(cell, 'cell', false);
+    canonCell(cell, 'cell');
+    if (fnHash(desc) !== cell.fn_hash)
+        (0, errors_js_1.fail)('E_FN_HASH_MISMATCH', 'the descriptor does not hash to cell.fn_hash', 'descriptor');
+    structFunction(desc, 'descriptor');
+    canonFunction(desc, 'descriptor');
+    const sig = desc.signature;
+    return (0, units_js_1.resolveUnit)(sig.returns, cell.args, 'descriptor.signature.returns', 'cell.args');
+}
 /** Receipt step 2 only: true when the receipt has the right members and JSON types. */
 function receiptStructure(v) {
     structReceipt(v, '$');