@datumesh/verify 0.1.1 → 0.2.0

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,20 +49,21 @@ function encodeValue(s) {
     }
     return out;
 }
+/**
+ * SPEC 5.4: the signature is taken as given (it comes from a descriptor already checked under
+ * section 7); only the declared argument names and types are used. Something that is not a
+ * signature at all is a programmer error.
+ */
 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');
     }
-    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 {
+        throw new TypeError('parseUri needs the function signature (descriptor.signature) as JSON');
     }
+    if (!(0, json_js_1.isObject)(sig) || !(0, json_js_1.isObject)(sig.args))
+        throw new TypeError('parseUri needs the function signature (descriptor.signature): an object with args');
     return sig;
 }
 /**
@@ -151,8 +152,15 @@ function parseUri(uri, signature) {
             args[p.name] = '*';
             continue;
         }
-        const type = declared[p.name].type;
+        const decl = declared[p.name];
+        const type = ((0, json_js_1.isObject)(decl) ? decl.type : undefined);
         const s = decodeValue(p.value, at(p.name));
+        // The signature is not validated (5.4), but a value is read by its declared type: a
+        // declaration without a string type is E_SCHEMA, an unknown type name E_CANON_TYPE.
+        if (typeof type !== 'string')
+            (0, errors_js_1.fail)('E_SCHEMA', `the signature declares ${p.name} without a string type`, `signature.args.${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));

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, '$');

package/dist/cjs/verify.d.ts

@@ -1,4 +1,6 @@
 import { type ErrorCode } from './errors.js';
+import { type JsonObject, type JsonValue } from './json.js';
+import { type Sources } from './keys.js';
 export interface VerifyResult {
     /** True when the receipt is signature-valid (and, if recompute was given, fully verified). */
     ok: boolean;
@@ -14,6 +16,8 @@ export interface VerifyResult {
     detail: string;
     /** Where the failure was found (a JSON path like `$.cell.args.base`), or null. */
     path: string | null;
+    /** True only when blob content was supplied and step 7.7 ran and passed. Does not change `level`. */
+    blobChecked: boolean;
 }
 /** Input for SPEC 10.1 step 7. The library does not evaluate functions; `value` is the result. */
 export interface Recompute {
@@ -27,12 +31,27 @@ export interface Recompute {
         value: string | boolean;
     };
 }
+declare class Stop extends Error {
+    readonly code: ErrorCode;
+    readonly detail: string;
+    readonly path: string | null;
+    constructor(code: ErrorCode, detail: string, path: string | null);
+}
 /**
  * Verify a receipt (SPEC 10.1). `receipt` is JSON text, UTF-8 bytes or a parsed object (only
  * text and bytes allow duplicate-member detection). `keys` is a key document, a KeysResult, a
- * {keyId: publicKeyHex} map, or an array of these. With `recompute`, step 7 runs too.
+ * {keyId: publicKeyHex} map, or an array of these. With `recompute`, step 7 runs too. With
+ * `blob`, the content of a blob value, step 7.7 runs last (after step 7 when recomputing,
+ * otherwise right after step 6): E_SCHEMA if the value is not a blob, E_BLOB_MISMATCH if the
+ * content does not match. It does not change `level`; `blobChecked` reports it.
  *
  * Never throws for an invalid receipt or bad key material; throws TypeError only when an
  * argument is of the wrong kind altogether.
  */
-export declare function verify(receipt: unknown, keys: unknown, recomputeArg?: Recompute | null): VerifyResult;
+export declare function verify(receipt: unknown, keys: unknown, recomputeArg?: Recompute | null, blob?: Uint8Array | ArrayBuffer | null): VerifyResult;
+/** Steps 1-6 for an already-parsed receipt (used by checkEnvelope). Throws a Stop. */
+export declare function verifyEmbedded(receipt: JsonValue, sources: Sources): {
+    receipt: JsonObject;
+    hash: string;
+};
+export { Stop };

package/dist/cjs/verify.js

@@ -1,6 +1,8 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.Stop = void 0;
 exports.verify = verify;
+exports.verifyEmbedded = verifyEmbedded;
 // Receipt verification (SPEC.md 10.1). Synchronous, offline, no global state, no logging.
 const errors_js_1 = require("./errors.js");
 const ed25519_js_1 = require("./ed25519.js");
@@ -8,6 +10,7 @@ const hash_js_1 = require("./hash.js");
 const json_js_1 = require("./json.js");
 const jcs_js_1 = require("./jcs.js");
 const keys_js_1 = require("./keys.js");
+const lexical_js_1 = require("./lexical.js");
 const validate_js_1 = require("./validate.js");
 class Stop extends Error {
     constructor(code, detail, path) {
@@ -17,6 +20,7 @@ class Stop extends Error {
         this.path = path;
     }
 }
+exports.Stop = Stop;
 function stop(code, detail, path = '$') {
     throw new Stop(code, detail, path);
 }
@@ -106,9 +110,10 @@ function recompute(receipt, rc, sources) {
     if (validNames.join('\u0000') !== declaredValid.join('\u0000')) {
         stop('E_VALID_MISMATCH', 'valid must echo exactly the declared valid-time arguments', '$.valid');
     }
-    // 7.4 Return type.
-    if (receipt.type !== sig.returns)
-        stop('E_RETURN_TYPE', `function returns ${String(sig.returns)}`, '$.type');
+    // 7.4 Return type: `returns`, or its `type` member when it is an object.
+    const rt = (0, validate_js_1.returnType)(sig);
+    if (receipt.type !== rt)
+        stop('E_RETURN_TYPE', `function returns ${rt}`, '$.type');
     // 7.5 Inputs.
     const declaredInputs = desc.inputs;
     const supplied = rc.inputs ?? {};
@@ -144,6 +149,28 @@ function recompute(receipt, rc, sources) {
     if (v.type !== receipt.type || v.value !== receipt.value)
         stop('E_VALUE_MISMATCH', 'recomputed value differs from the receipt', '$.value');
 }
+/**
+ * Step 7.7: content is only for a blob value (E_SCHEMA otherwise); it has exactly `length`
+ * bytes, then a SHA-256 equal to the blob's hash (E_BLOB_MISMATCH).
+ */
+function checkContent(receipt, content) {
+    if (receipt.type !== 'blob')
+        stop('E_SCHEMA', `content was supplied, but the value is a ${String(receipt.type)}, not a blob`, '$.type');
+    const blob = (0, lexical_js_1.checkBlob)(receipt.value, '$.value'); // already checked in step 3
+    if (content.length !== blob.length)
+        stop('E_BLOB_MISMATCH', `content is ${content.length} bytes, the blob says ${blob.length}`, '$.value');
+    if ((0, hash_js_1.sha256Hex)(content) !== blob.sha256)
+        stop('E_BLOB_MISMATCH', "the content's SHA-256 is not the blob's hash", '$.value');
+}
+function checkBlobArg(b) {
+    if (b === undefined || b === null)
+        return null;
+    if (b instanceof Uint8Array)
+        return b;
+    if (b instanceof ArrayBuffer)
+        return new Uint8Array(b);
+    throw new TypeError('blob must be the content bytes (Uint8Array or ArrayBuffer)');
+}
 function checkRecomputeArg(rc) {
     if (rc === undefined || rc === null)
         return null;
@@ -161,32 +188,45 @@ function checkRecomputeArg(rc) {
 /**
  * Verify a receipt (SPEC 10.1). `receipt` is JSON text, UTF-8 bytes or a parsed object (only
  * text and bytes allow duplicate-member detection). `keys` is a key document, a KeysResult, a
- * {keyId: publicKeyHex} map, or an array of these. With `recompute`, step 7 runs too.
+ * {keyId: publicKeyHex} map, or an array of these. With `recompute`, step 7 runs too. With
+ * `blob`, the content of a blob value, step 7.7 runs last (after step 7 when recomputing,
+ * otherwise right after step 6): E_SCHEMA if the value is not a blob, E_BLOB_MISMATCH if the
+ * content does not match. It does not change `level`; `blobChecked` reports it.
  *
  * Never throws for an invalid receipt or bad key material; throws TypeError only when an
  * argument is of the wrong kind altogether.
  */
-function verify(receipt, keys, recomputeArg) {
+function verify(receipt, keys, recomputeArg, blob) {
     const sources = (0, keys_js_1.collectSources)(keys);
     const rc = checkRecomputeArg(recomputeArg);
+    const content = checkBlobArg(blob);
     let hash = null;
     try {
         const { receipt: r } = verifySigned(receipt, sources, (h) => (hash = h));
         if (rc)
             recompute(r, rc, sources);
+        const checked = content !== null;
+        if (checked)
+            checkContent(r, content);
+        const what = rc ? 'fully verified: signature valid and value recomputed' : `signature-valid: signed by ${r.computed_by}`;
         return {
             ok: true,
             code: 'OK',
             level: rc ? 'recomputed' : 'signed',
             hash,
             key: r.computed_by,
-            detail: rc ? 'fully verified: signature valid and value recomputed' : `signature-valid: signed by ${r.computed_by}`,
+            detail: checked ? `${what}; blob content matches` : what,
             path: null,
+            blobChecked: checked,
         };
     }
     catch (e) {
         if (e instanceof Stop)
-            return { ok: false, code: e.code, level: null, hash, key: null, detail: e.detail, path: e.path };
+            return { ok: false, code: e.code, level: null, hash, key: null, detail: e.detail, path: e.path, blobChecked: false };
         throw e; // a bug in this library, not a property of the receipt
     }
 }
+/** Steps 1-6 for an already-parsed receipt (used by checkEnvelope). Throws a Stop. */
+function verifyEmbedded(receipt, sources) {
+    return verifySigned(receipt, sources, () => undefined);
+}