@datumesh/verify 0.2.1 → 0.3.0

package/README.md

@@ -1,6 +1,6 @@
 # @datumesh/verify
 
-Verify [Datumesh](https://datumesh.com) receipts in JavaScript: signed answers for addressable data cells, checked offline against strict RFC 8785 canonical JSON and Ed25519, following the [Datumesh specification](https://github.com/datumesh-com/datumesh-spec) revision `spec-0.2.1` and passing all of its test vectors.
+Verify [Datumesh](https://datumesh.com) receipts in JavaScript: signed answers for addressable data cells, checked offline against strict RFC 8785 canonical JSON and Ed25519, following the [Datumesh specification](https://github.com/datumesh-com/datumesh-spec) revision `spec-0.3.0` and passing all of its test vectors.
 
 ```sh
 npm install @datumesh/verify
@@ -31,10 +31,10 @@ console.log(verify(vector.input, keys).code); // OK
 
 ## What it does
 
-- `verify(receipt, keys, recompute?, blob?)` runs the verification procedure of SPEC.md 10.1 and returns `{ ok, code, level, hash, key, detail, path, blobChecked }`. It is synchronous, never touches the network and never throws for a bad receipt or bad key material; failures come back as the spec's error codes (`E_SIGNATURE`, `E_KEY_NOT_VALID`, ...). `level` is `"signed"`, or `"recomputed"` when you pass the descriptor, the input receipts and the value you obtained by evaluating the function (the library checks lineage and compares; it does not evaluate functions). For a receipt whose value is a `blob`, pass the content bytes as `blob` to check their length and SHA-256 (`E_BLOB_MISMATCH`; `blobChecked` is then true).
+- `verify(receipt, keys, recompute?, blob?)` runs the verification procedure of SPEC.md 10.1 and returns `{ ok, code, level, hash, key, detail, path, blobChecked }`. It is synchronous, never touches the network and never throws for a bad receipt or bad key material; failures come back as the spec's error codes (`E_SIGNATURE`, `E_KEY_NOT_VALID`, ...). `level` is `"signed"`, or `"recomputed"` when you pass the descriptor, the input receipts and the value you obtained by evaluating the function (the library checks lineage and compares; it does not evaluate functions). If you could not evaluate it, leave out the value: when the descriptor, arguments and inputs check out, the result is `ok` at level `"signed"` with `code` `"E_EVAL_UNAVAILABLE"`, the one code reported with success. For a receipt whose value is a `blob`, pass the content bytes as `blob` to check their length and SHA-256 (`E_BLOB_MISMATCH`; `blobChecked` is then true).
 - `keys` is a key document, the result of `keysFromResponse` / `fetchKeys`, a `{ keyId: publicKeyHex }` map, or an array of these (one per host for lineage).
 - `fetchKeys(host)` is the only function that uses the network: one `GET https://<host>/.well-known/datumesh.json`, no redirects, 10 s timeout, using the platform's `fetch` and TLS verification.
-- `checkEnvelope(status, body, keys, request)` checks a mesh's response envelope (SPEC.md 5.5) against its HTTP status, verifies the embedded receipt through the signature, and checks that it answers your request (`request` is `{ cell_id, asof? }`: the id of the cell you asked for and the `asof` you asked with, if any), returning `{ ok, code, outcome, trust, receiptHash, detail, path }`. The envelope itself is unsigned: `stale`, `superseded_by` and `verified` remain the mesh's claims.
+- `checkEnvelope(status, body, keys, request)` checks a mesh's response envelope (SPEC.md 5.5) against its HTTP status, verifies the embedded receipt through the signature, and checks that it answers your request (`request` is `{ cell_id, asof? }`: the id of the cell you asked for and the `asof` you asked with, if any), returning `{ ok, code, outcome, trust, receiptHash, detail, path }`. The receipt's `asof` must be at or before the requested one, for `ok` as for `stale`. The envelope itself is unsigned: that an `ok` receipt is the latest version, `stale`, `superseded_by` and `verified` remain the mesh's claims.
 - `resolvedUnit(descriptor, cell)` gives the unit of a cell's value from its function's declared units (`"USD/EUR"`, `"degC"`, or `null` for a non-number), using the closed list of `units.md` shipped with the package. The library never converts or checks values against units.
 - `canonicalize(obj, kind)`, `cellHash`, `receiptHash`, `functionHash`, `parseUri(uri, signature)`, `formatUri(ref)` and `keyId` expose canonical forms, hashes and cell URIs. These and `resolvedUnit` throw `DatumeshError` (with `.code` and `.path`).
 

package/dist/cjs/envelope.js

@@ -223,12 +223,11 @@ function checkEnvelope(status, body, keys, request) {
     const cellId = (0, hash_js_1.sha256Hex)((0, jcs_js_1.jcsBytes)(r.receipt.cell));
     if (cellId !== request.cell_id)
         return fail('E_ENVELOPE', `the receipt is for cell ${cellId}, not the requested ${request.cell_id}`, '$.receipt.cell', r.hash);
-    // With a requested asof: equal for ok; at or before it for stale (D31). Instants are fixed
+    // With a requested asof: at or before it, for ok and stale alike (D31, revised in spec-0.3.0). Instants are fixed
     // width, so string order is time order (SPEC 3.3).
     const asof = r.receipt.asof;
-    if (request.asof !== undefined && (outcome === 'stale' ? !(asof <= request.asof) : asof !== request.asof)) {
-        const want = outcome === 'stale' ? `at or before the requested ${request.asof}` : `the requested ${request.asof}`;
-        return fail('E_ENVELOPE', `the receipt answers asof ${asof}, not ${want}`, '$.receipt.asof', r.hash);
+    if (request.asof !== undefined && !(asof <= request.asof)) {
+        return fail('E_ENVELOPE', `the receipt answers asof ${asof}, later than the requested ${request.asof}`, '$.receipt.asof', r.hash);
     }
     // Step 6.
     const trust = env.trust;

package/dist/cjs/errors.d.ts

@@ -1,7 +1,10 @@
 /** The spec revision this library conforms to. */
-export declare const SPEC_VERSION = "spec-0.2.1";
-/** Every error code defined by SPEC.md 10.2, in the order of that table. */
-export declare const ERROR_CODES: readonly ["E_PARSE_JSON", "E_PARSE_DUPLICATE_KEY", "E_PARSE_URI", "E_SCHEMA", "E_CANON_NAME", "E_CANON_ARG_NAME", "E_CANON_ARG_DUPLICATE", "E_CANON_ARG_ORDER", "E_CANON_PERCENT", "E_CANON_TYPE", "E_CANON_NUMBER", "E_CANON_UNIT", "E_CANON_DATE", "E_CANON_INSTANT", "E_CANON_STRING", "E_CANON_BLOB", "E_CANON_HEX", "E_CANON_LICENCE", "E_CANON_SET", "E_CANON_LIMIT", "E_SLICE", "E_PUBLISHER_MISMATCH", "E_VALID_MISMATCH", "E_TIME_ORDER", "E_ARG_UNKNOWN", "E_ARG_MISSING", "E_KEY_UNAVAILABLE", "E_KEY_DOC", "E_KEY_UNKNOWN", "E_KEY_NOT_VALID", "E_SIGNATURE", "E_FN_UNAVAILABLE", "E_FN_HASH_MISMATCH", "E_ARG_TYPE", "E_RETURN_TYPE", "E_INPUT_UNAVAILABLE", "E_INPUT_INVALID", "E_INPUT_UNDECLARED", "E_VALUE_MISMATCH", "E_BLOB_MISMATCH", "E_ENVELOPE"];
+export declare const SPEC_VERSION = "spec-0.3.0";
+/**
+ * Every error code defined by SPEC.md 10.2, in the order of that table. `E_EVAL_UNAVAILABLE` is
+ * the one code that is not a failure: `verify` reports it with success (10.1 step 7.6).
+ */
+export declare const ERROR_CODES: readonly ["E_PARSE_JSON", "E_PARSE_DUPLICATE_KEY", "E_PARSE_URI", "E_SCHEMA", "E_CANON_NAME", "E_CANON_ARG_NAME", "E_CANON_ARG_DUPLICATE", "E_CANON_ARG_ORDER", "E_CANON_PERCENT", "E_CANON_TYPE", "E_CANON_NUMBER", "E_CANON_UNIT", "E_CANON_DATE", "E_CANON_INSTANT", "E_CANON_STRING", "E_CANON_BLOB", "E_CANON_HEX", "E_CANON_LICENCE", "E_CANON_SET", "E_CANON_LIMIT", "E_SLICE", "E_PUBLISHER_MISMATCH", "E_VALID_MISMATCH", "E_TIME_ORDER", "E_ARG_UNKNOWN", "E_ARG_MISSING", "E_KEY_UNAVAILABLE", "E_KEY_DOC", "E_KEY_UNKNOWN", "E_KEY_NOT_VALID", "E_SIGNATURE", "E_FN_UNAVAILABLE", "E_FN_HASH_MISMATCH", "E_ARG_TYPE", "E_RETURN_TYPE", "E_INPUT_UNAVAILABLE", "E_INPUT_INVALID", "E_INPUT_UNDECLARED", "E_VALUE_MISMATCH", "E_EVAL_UNAVAILABLE", "E_BLOB_MISMATCH", "E_ENVELOPE"];
 export type ErrorCode = (typeof ERROR_CODES)[number];
 /** A Datumesh rule was broken. `code` is a SPEC.md 10.2 code; `path` locates the failure. */
 export declare class DatumeshError extends Error {

package/dist/cjs/errors.js

@@ -3,8 +3,11 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.DatumeshError = exports.ERROR_CODES = exports.SPEC_VERSION = void 0;
 exports.fail = fail;
 /** The spec revision this library conforms to. */
-exports.SPEC_VERSION = 'spec-0.2.1';
-/** Every error code defined by SPEC.md 10.2, in the order of that table. */
+exports.SPEC_VERSION = 'spec-0.3.0';
+/**
+ * Every error code defined by SPEC.md 10.2, in the order of that table. `E_EVAL_UNAVAILABLE` is
+ * the one code that is not a failure: `verify` reports it with success (10.1 step 7.6).
+ */
 exports.ERROR_CODES = [
     'E_PARSE_JSON',
     'E_PARSE_DUPLICATE_KEY',
@@ -45,6 +48,7 @@ exports.ERROR_CODES = [
     'E_INPUT_INVALID',
     'E_INPUT_UNDECLARED',
     'E_VALUE_MISMATCH',
+    'E_EVAL_UNAVAILABLE',
     'E_BLOB_MISMATCH',
     'E_ENVELOPE',
 ];

package/dist/cjs/index.d.ts

@@ -7,7 +7,7 @@ export { keysFromResponse, keysFromDocument, fetchKeys, FETCH_TIMEOUT_MS, FETCH_
 export type { Kind } from './validate.js';
 export type { JsonValue } from './json.js';
 /** Library version. */
-export declare const VERSION = "0.2.1";
+export declare const VERSION = "0.3.0";
 /**
  * Validate `input` as `kind` and return its RFC 8785 canonical bytes. `input` is JSON text,
  * UTF-8 bytes, or an already-parsed value. `kind` is "scalar", "cell", "ref", "function" or

package/dist/cjs/index.js

@@ -9,7 +9,7 @@ exports.receiptPayload = receiptPayload;
 exports.resolvedUnit = resolvedUnit;
 exports.keyId = keyId;
 /**
- * @datumesh/verify: verify Datumesh receipts (SPEC.md, revision spec-0.2.1).
+ * @datumesh/verify: verify Datumesh receipts (SPEC.md, revision spec-0.3.0).
  *
  * Everything here is synchronous and offline except fetchKeys, the only function that uses the
  * network.
@@ -39,7 +39,7 @@ Object.defineProperty(exports, "fetchKeys", { enumerable: true, get: function ()
 Object.defineProperty(exports, "FETCH_TIMEOUT_MS", { enumerable: true, get: function () { return keys_js_1.FETCH_TIMEOUT_MS; } });
 Object.defineProperty(exports, "FETCH_MAX_BYTES", { enumerable: true, get: function () { return keys_js_1.FETCH_MAX_BYTES; } });
 /** Library version. */
-exports.VERSION = '0.2.1';
+exports.VERSION = '0.3.0';
 function parseAndValidate(input, kind) {
     if (kind !== undefined && kind !== null && !validate_js_1.KINDS.includes(kind))
         throw new TypeError(`unknown kind ${JSON.stringify(kind)}; expected one of ${validate_js_1.KINDS.join(', ')}`);

package/dist/cjs/keys.d.ts

@@ -23,10 +23,11 @@ export type KeyMap = Record<string, string>;
 export type KeySource = KeysResult | KeyMap | Record<string, unknown> | KeySource[];
 /**
  * Interpret the HTTPS response for https://<host>/.well-known/datumesh.json (SPEC 9.3).
- * `status` is the HTTP status, or null for a network, DNS, TLS or timeout failure. `body` is the
- * response body as text or bytes. Never throws.
+ * `status` is the HTTP status, or null for a network, DNS, TLS or timeout failure. Only the
+ * integer 200 is a retrieved document: any other value (a string "200" included, or undefined)
+ * is E_KEY_UNAVAILABLE. `body` is the response body as text or bytes. Never throws.
  */
-export declare function keysFromResponse(host: string, status: number | null, body?: string | Uint8Array | null): KeysResult;
+export declare function keysFromResponse(host: string, status: unknown, body?: string | Uint8Array | null): KeysResult;
 /**
  * Validate an already-parsed key document (its `host` member names the host it covers).
  * Never throws.

package/dist/cjs/keys.js

@@ -110,15 +110,21 @@ function docResult(host, parse) {
 }
 /**
  * Interpret the HTTPS response for https://<host>/.well-known/datumesh.json (SPEC 9.3).
- * `status` is the HTTP status, or null for a network, DNS, TLS or timeout failure. `body` is the
- * response body as text or bytes. Never throws.
+ * `status` is the HTTP status, or null for a network, DNS, TLS or timeout failure. Only the
+ * integer 200 is a retrieved document: any other value (a string "200" included, or undefined)
+ * is E_KEY_UNAVAILABLE. `body` is the response body as text or bytes. Never throws.
  */
 function keysFromResponse(host, status, body) {
     const h = typeof host === 'string' ? host : String(host);
     try {
-        if (status === null || status === undefined) {
+        if (status === null) {
             return { ok: false, code: 'E_KEY_UNAVAILABLE', host: h, detail: 'network, DNS, TLS or timeout failure' };
         }
+        if (status === undefined)
+            return { ok: false, code: 'E_KEY_UNAVAILABLE', host: h, detail: 'no HTTP status' };
+        if (typeof status !== 'number') {
+            return { ok: false, code: 'E_KEY_UNAVAILABLE', host: h, detail: `HTTP status ${JSON.stringify(String(status))} is not an integer (only the integer 200 is a retrieved document)` };
+        }
         if (status !== 200) {
             return { ok: false, code: 'E_KEY_UNAVAILABLE', host: h, detail: `HTTP status ${String(status)} (only 200 is accepted; redirects are not followed)` };
         }

package/dist/cjs/verify.d.ts

@@ -2,9 +2,17 @@ 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). */
+    /**
+     * True when the receipt is signature-valid (and, if recompute was given with a value, fully
+     * verified).
+     */
     ok: boolean;
-    /** "OK" or a SPEC 10.2 error code. */
+    /**
+     * "OK" or a SPEC 10.2 error code. With `ok` true it is "OK", or `E_EVAL_UNAVAILABLE` when
+     * recompute was given without a value: steps 7.1-7.5 passed but the function was not evaluated
+     * (SPEC 10.1 step 7.6), so `level` is "signed" and `path` is "$.value". That is the one code
+     * reported with success.
+     */
     code: 'OK' | ErrorCode;
     /** "signed" (steps 1-6) or "recomputed" (steps 1-7) when ok, else null. */
     level: 'signed' | 'recomputed' | null;
@@ -21,12 +29,21 @@ export interface VerifyResult {
 }
 /** Input for SPEC 10.1 step 7. The library does not evaluate functions; `value` is the result. */
 export interface Recompute {
-    /** The function descriptor for cell.fn_hash (object or JSON text); absent: E_FN_UNAVAILABLE. */
+    /**
+     * The function descriptor for cell.fn_hash: a parsed JSON value, or JSON text / UTF-8 bytes,
+     * parsed strictly first. Absent (undefined): E_FN_UNAVAILABLE. Anything else obtained, `null`
+     * included, is a descriptor offered: if it is not the descriptor it fails the hash check
+     * (E_FN_HASH_MISMATCH; SPEC 10.1 step 7.1). A JS string is always JSON text.
+     */
     descriptor?: unknown;
     /** Input receipts by receipt hash, as JSON text (or bytes, or parsed objects). */
     inputs?: Record<string, unknown>;
-    /** What evaluating the function produced: a typed scalar. */
-    value: {
+    /**
+     * What evaluating the function produced: a typed scalar. Absent (undefined) when the function
+     * could not be evaluated: once 7.1-7.5 pass, the result is success at level "signed" with code
+     * E_EVAL_UNAVAILABLE (SPEC 10.1 step 7.6).
+     */
+    value?: {
         type: string;
         value: string | boolean;
     };
@@ -40,7 +57,9 @@ declare class Stop extends Error {
 /**
  * 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. With
+ * {keyId: publicKeyHex} map, or an array of these. With `recompute`, step 7 runs too; without
+ * its `value`, steps 7.1-7.5 run and the result is success at level "signed" with code
+ * E_EVAL_UNAVAILABLE (path "$.value") unless they fail. 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.

package/dist/cjs/verify.js

@@ -69,11 +69,12 @@ function verifySigned(input, sources, setHash) {
     }
     return { receipt, hash };
 }
+/** Step 7. Throws Stop; returns false when 7.6 could not run (no value: E_EVAL_UNAVAILABLE). */
 function recompute(receipt, rc, sources) {
     const cell = receipt.cell;
     const cellArgs = cell.args;
-    // 7.1 Descriptor.
-    if (rc.descriptor === undefined || rc.descriptor === null)
+    // 7.1 Descriptor. Only obtaining nothing is unavailability; null is a descriptor offered (D35).
+    if (rc.descriptor === undefined)
         stop('E_FN_UNAVAILABLE', `no descriptor for ${cell.fn_hash}`, '$.cell.fn_hash');
     let desc;
     try {
@@ -136,18 +137,23 @@ function recompute(receipt, rc, sources) {
         if (!declaredInputs.includes(`${ic.ns}/${ic.fn}`)) {
             stop('E_INPUT_UNDECLARED', `input ${h} is a cell of an undeclared function`, '$.inputs');
         }
-        if (inner.receipt.asof !== receipt.asof)
-            stop('E_TIME_ORDER', "input receipts must share the receipt's asof", '$.inputs');
+        // At or before the receipt's asof (D17, revised in spec-0.3.0); instants are fixed width, so
+        // string order is time order (SPEC 3.3).
+        if (!(inner.receipt.asof <= receipt.asof))
+            stop('E_TIME_ORDER', `input ${h} has asof ${inner.receipt.asof}, after the receipt's asof`, '$.inputs');
         const itx = inner.receipt.tx;
         if (latestTx === null || itx > latestTx)
             latestTx = itx;
     }
     if (latestTx !== null && receipt.tx !== latestTx)
         stop('E_TIME_ORDER', 'tx must be the latest input tx', '$.tx');
-    // 7.6 Value.
+    // 7.6 Value. No value: the function could not be evaluated (E_EVAL_UNAVAILABLE, not a failure).
     const v = rc.value;
+    if (v === undefined)
+        return false;
     if (v.type !== receipt.type || v.value !== receipt.value)
         stop('E_VALUE_MISMATCH', 'recomputed value differs from the receipt', '$.value');
+    return true;
 }
 /**
  * Step 7.7: content is only for a blob value (E_SCHEMA otherwise); it has exactly `length`
@@ -177,8 +183,8 @@ function checkRecomputeArg(rc) {
     if (typeof rc !== 'object' || Array.isArray(rc))
         throw new TypeError('recompute must be an object {descriptor, inputs, value}');
     const r = rc;
-    if (!r.value || typeof r.value !== 'object' || typeof r.value.type !== 'string' || (typeof r.value.value !== 'string' && typeof r.value.value !== 'boolean')) {
-        throw new TypeError('recompute.value must be the evaluated typed scalar {type, value}');
+    if (r.value !== undefined && (!r.value || typeof r.value !== 'object' || typeof r.value.type !== 'string' || (typeof r.value.value !== 'string' && typeof r.value.value !== 'boolean'))) {
+        throw new TypeError('recompute.value must be the evaluated typed scalar {type, value}, or absent when the function could not be evaluated');
     }
     if (r.inputs !== undefined && (typeof r.inputs !== 'object' || r.inputs === null || Array.isArray(r.inputs))) {
         throw new TypeError('recompute.inputs must be an object mapping receipt hash to receipt JSON');
@@ -188,7 +194,9 @@ 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. With
+ * {keyId: publicKeyHex} map, or an array of these. With `recompute`, step 7 runs too; without
+ * its `value`, steps 7.1-7.5 run and the result is success at level "signed" with code
+ * E_EVAL_UNAVAILABLE (path "$.value") unless they fail. 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.
@@ -203,20 +211,24 @@ function verify(receipt, keys, recomputeArg, blob) {
     let hash = null;
     try {
         const { receipt: r } = verifySigned(receipt, sources, (h) => (hash = h));
-        if (rc)
-            recompute(r, rc, sources);
+        const evaluated = rc ? recompute(r, rc, sources) : false;
         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}`;
+            checkContent(r, content); // 7.7 also after E_EVAL_UNAVAILABLE; its failure replaces the code
+        const unavailable = rc !== null && !evaluated;
+        const what = evaluated
+            ? 'fully verified: signature valid and value recomputed'
+            : unavailable
+                ? `signature-valid: signed by ${r.computed_by}; descriptor, arguments and inputs check out, but the function could not be evaluated, so the value was not recomputed`
+                : `signature-valid: signed by ${r.computed_by}`;
         return {
             ok: true,
-            code: 'OK',
-            level: rc ? 'recomputed' : 'signed',
+            code: unavailable ? 'E_EVAL_UNAVAILABLE' : 'OK',
+            level: evaluated ? 'recomputed' : 'signed',
             hash,
             key: r.computed_by,
             detail: checked ? `${what}; blob content matches` : what,
-            path: null,
+            path: unavailable ? '$.value' : null,
             blobChecked: checked,
         };
     }

package/dist/esm/envelope.js

@@ -220,12 +220,11 @@ export function checkEnvelope(status, body, keys, request) {
     const cellId = sha256Hex(jcsBytes(r.receipt.cell));
     if (cellId !== request.cell_id)
         return fail('E_ENVELOPE', `the receipt is for cell ${cellId}, not the requested ${request.cell_id}`, '$.receipt.cell', r.hash);
-    // With a requested asof: equal for ok; at or before it for stale (D31). Instants are fixed
+    // With a requested asof: at or before it, for ok and stale alike (D31, revised in spec-0.3.0). Instants are fixed
     // width, so string order is time order (SPEC 3.3).
     const asof = r.receipt.asof;
-    if (request.asof !== undefined && (outcome === 'stale' ? !(asof <= request.asof) : asof !== request.asof)) {
-        const want = outcome === 'stale' ? `at or before the requested ${request.asof}` : `the requested ${request.asof}`;
-        return fail('E_ENVELOPE', `the receipt answers asof ${asof}, not ${want}`, '$.receipt.asof', r.hash);
+    if (request.asof !== undefined && !(asof <= request.asof)) {
+        return fail('E_ENVELOPE', `the receipt answers asof ${asof}, later than the requested ${request.asof}`, '$.receipt.asof', r.hash);
     }
     // Step 6.
     const trust = env.trust;

package/dist/esm/errors.d.ts

@@ -1,7 +1,10 @@
 /** The spec revision this library conforms to. */
-export declare const SPEC_VERSION = "spec-0.2.1";
-/** Every error code defined by SPEC.md 10.2, in the order of that table. */
-export declare const ERROR_CODES: readonly ["E_PARSE_JSON", "E_PARSE_DUPLICATE_KEY", "E_PARSE_URI", "E_SCHEMA", "E_CANON_NAME", "E_CANON_ARG_NAME", "E_CANON_ARG_DUPLICATE", "E_CANON_ARG_ORDER", "E_CANON_PERCENT", "E_CANON_TYPE", "E_CANON_NUMBER", "E_CANON_UNIT", "E_CANON_DATE", "E_CANON_INSTANT", "E_CANON_STRING", "E_CANON_BLOB", "E_CANON_HEX", "E_CANON_LICENCE", "E_CANON_SET", "E_CANON_LIMIT", "E_SLICE", "E_PUBLISHER_MISMATCH", "E_VALID_MISMATCH", "E_TIME_ORDER", "E_ARG_UNKNOWN", "E_ARG_MISSING", "E_KEY_UNAVAILABLE", "E_KEY_DOC", "E_KEY_UNKNOWN", "E_KEY_NOT_VALID", "E_SIGNATURE", "E_FN_UNAVAILABLE", "E_FN_HASH_MISMATCH", "E_ARG_TYPE", "E_RETURN_TYPE", "E_INPUT_UNAVAILABLE", "E_INPUT_INVALID", "E_INPUT_UNDECLARED", "E_VALUE_MISMATCH", "E_BLOB_MISMATCH", "E_ENVELOPE"];
+export declare const SPEC_VERSION = "spec-0.3.0";
+/**
+ * Every error code defined by SPEC.md 10.2, in the order of that table. `E_EVAL_UNAVAILABLE` is
+ * the one code that is not a failure: `verify` reports it with success (10.1 step 7.6).
+ */
+export declare const ERROR_CODES: readonly ["E_PARSE_JSON", "E_PARSE_DUPLICATE_KEY", "E_PARSE_URI", "E_SCHEMA", "E_CANON_NAME", "E_CANON_ARG_NAME", "E_CANON_ARG_DUPLICATE", "E_CANON_ARG_ORDER", "E_CANON_PERCENT", "E_CANON_TYPE", "E_CANON_NUMBER", "E_CANON_UNIT", "E_CANON_DATE", "E_CANON_INSTANT", "E_CANON_STRING", "E_CANON_BLOB", "E_CANON_HEX", "E_CANON_LICENCE", "E_CANON_SET", "E_CANON_LIMIT", "E_SLICE", "E_PUBLISHER_MISMATCH", "E_VALID_MISMATCH", "E_TIME_ORDER", "E_ARG_UNKNOWN", "E_ARG_MISSING", "E_KEY_UNAVAILABLE", "E_KEY_DOC", "E_KEY_UNKNOWN", "E_KEY_NOT_VALID", "E_SIGNATURE", "E_FN_UNAVAILABLE", "E_FN_HASH_MISMATCH", "E_ARG_TYPE", "E_RETURN_TYPE", "E_INPUT_UNAVAILABLE", "E_INPUT_INVALID", "E_INPUT_UNDECLARED", "E_VALUE_MISMATCH", "E_EVAL_UNAVAILABLE", "E_BLOB_MISMATCH", "E_ENVELOPE"];
 export type ErrorCode = (typeof ERROR_CODES)[number];
 /** A Datumesh rule was broken. `code` is a SPEC.md 10.2 code; `path` locates the failure. */
 export declare class DatumeshError extends Error {

package/dist/esm/errors.js

@@ -1,6 +1,9 @@
 /** The spec revision this library conforms to. */
-export const SPEC_VERSION = 'spec-0.2.1';
-/** Every error code defined by SPEC.md 10.2, in the order of that table. */
+export const SPEC_VERSION = 'spec-0.3.0';
+/**
+ * Every error code defined by SPEC.md 10.2, in the order of that table. `E_EVAL_UNAVAILABLE` is
+ * the one code that is not a failure: `verify` reports it with success (10.1 step 7.6).
+ */
 export const ERROR_CODES = [
     'E_PARSE_JSON',
     'E_PARSE_DUPLICATE_KEY',
@@ -41,6 +44,7 @@ export const ERROR_CODES = [
     'E_INPUT_INVALID',
     'E_INPUT_UNDECLARED',
     'E_VALUE_MISMATCH',
+    'E_EVAL_UNAVAILABLE',
     'E_BLOB_MISMATCH',
     'E_ENVELOPE',
 ];

package/dist/esm/index.d.ts

@@ -7,7 +7,7 @@ export { keysFromResponse, keysFromDocument, fetchKeys, FETCH_TIMEOUT_MS, FETCH_
 export type { Kind } from './validate.js';
 export type { JsonValue } from './json.js';
 /** Library version. */
-export declare const VERSION = "0.2.1";
+export declare const VERSION = "0.3.0";
 /**
  * Validate `input` as `kind` and return its RFC 8785 canonical bytes. `input` is JSON text,
  * UTF-8 bytes, or an already-parsed value. `kind` is "scalar", "cell", "ref", "function" or

package/dist/esm/index.js

@@ -1,5 +1,5 @@
 /**
- * @datumesh/verify: verify Datumesh receipts (SPEC.md, revision spec-0.2.1).
+ * @datumesh/verify: verify Datumesh receipts (SPEC.md, revision spec-0.3.0).
  *
  * Everything here is synchronous and offline except fetchKeys, the only function that uses the
  * network.
@@ -16,7 +16,7 @@ export { checkEnvelope } from './envelope.js';
 export { parseUri, formatUri, httpsUrl } from './uri.js';
 export { keysFromResponse, keysFromDocument, fetchKeys, FETCH_TIMEOUT_MS, FETCH_MAX_BYTES } from './keys.js';
 /** Library version. */
-export const VERSION = '0.2.1';
+export const VERSION = '0.3.0';
 function parseAndValidate(input, kind) {
     if (kind !== undefined && kind !== null && !KINDS.includes(kind))
         throw new TypeError(`unknown kind ${JSON.stringify(kind)}; expected one of ${KINDS.join(', ')}`);

package/dist/esm/keys.d.ts

@@ -23,10 +23,11 @@ export type KeyMap = Record<string, string>;
 export type KeySource = KeysResult | KeyMap | Record<string, unknown> | KeySource[];
 /**
  * Interpret the HTTPS response for https://<host>/.well-known/datumesh.json (SPEC 9.3).
- * `status` is the HTTP status, or null for a network, DNS, TLS or timeout failure. `body` is the
- * response body as text or bytes. Never throws.
+ * `status` is the HTTP status, or null for a network, DNS, TLS or timeout failure. Only the
+ * integer 200 is a retrieved document: any other value (a string "200" included, or undefined)
+ * is E_KEY_UNAVAILABLE. `body` is the response body as text or bytes. Never throws.
  */
-export declare function keysFromResponse(host: string, status: number | null, body?: string | Uint8Array | null): KeysResult;
+export declare function keysFromResponse(host: string, status: unknown, body?: string | Uint8Array | null): KeysResult;
 /**
  * Validate an already-parsed key document (its `host` member names the host it covers).
  * Never throws.

package/dist/esm/keys.js

@@ -102,15 +102,21 @@ function docResult(host, parse) {
 }
 /**
  * Interpret the HTTPS response for https://<host>/.well-known/datumesh.json (SPEC 9.3).
- * `status` is the HTTP status, or null for a network, DNS, TLS or timeout failure. `body` is the
- * response body as text or bytes. Never throws.
+ * `status` is the HTTP status, or null for a network, DNS, TLS or timeout failure. Only the
+ * integer 200 is a retrieved document: any other value (a string "200" included, or undefined)
+ * is E_KEY_UNAVAILABLE. `body` is the response body as text or bytes. Never throws.
  */
 export function keysFromResponse(host, status, body) {
     const h = typeof host === 'string' ? host : String(host);
     try {
-        if (status === null || status === undefined) {
+        if (status === null) {
             return { ok: false, code: 'E_KEY_UNAVAILABLE', host: h, detail: 'network, DNS, TLS or timeout failure' };
         }
+        if (status === undefined)
+            return { ok: false, code: 'E_KEY_UNAVAILABLE', host: h, detail: 'no HTTP status' };
+        if (typeof status !== 'number') {
+            return { ok: false, code: 'E_KEY_UNAVAILABLE', host: h, detail: `HTTP status ${JSON.stringify(String(status))} is not an integer (only the integer 200 is a retrieved document)` };
+        }
         if (status !== 200) {
             return { ok: false, code: 'E_KEY_UNAVAILABLE', host: h, detail: `HTTP status ${String(status)} (only 200 is accepted; redirects are not followed)` };
         }

package/dist/esm/verify.d.ts

@@ -2,9 +2,17 @@ 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). */
+    /**
+     * True when the receipt is signature-valid (and, if recompute was given with a value, fully
+     * verified).
+     */
     ok: boolean;
-    /** "OK" or a SPEC 10.2 error code. */
+    /**
+     * "OK" or a SPEC 10.2 error code. With `ok` true it is "OK", or `E_EVAL_UNAVAILABLE` when
+     * recompute was given without a value: steps 7.1-7.5 passed but the function was not evaluated
+     * (SPEC 10.1 step 7.6), so `level` is "signed" and `path` is "$.value". That is the one code
+     * reported with success.
+     */
     code: 'OK' | ErrorCode;
     /** "signed" (steps 1-6) or "recomputed" (steps 1-7) when ok, else null. */
     level: 'signed' | 'recomputed' | null;
@@ -21,12 +29,21 @@ export interface VerifyResult {
 }
 /** Input for SPEC 10.1 step 7. The library does not evaluate functions; `value` is the result. */
 export interface Recompute {
-    /** The function descriptor for cell.fn_hash (object or JSON text); absent: E_FN_UNAVAILABLE. */
+    /**
+     * The function descriptor for cell.fn_hash: a parsed JSON value, or JSON text / UTF-8 bytes,
+     * parsed strictly first. Absent (undefined): E_FN_UNAVAILABLE. Anything else obtained, `null`
+     * included, is a descriptor offered: if it is not the descriptor it fails the hash check
+     * (E_FN_HASH_MISMATCH; SPEC 10.1 step 7.1). A JS string is always JSON text.
+     */
     descriptor?: unknown;
     /** Input receipts by receipt hash, as JSON text (or bytes, or parsed objects). */
     inputs?: Record<string, unknown>;
-    /** What evaluating the function produced: a typed scalar. */
-    value: {
+    /**
+     * What evaluating the function produced: a typed scalar. Absent (undefined) when the function
+     * could not be evaluated: once 7.1-7.5 pass, the result is success at level "signed" with code
+     * E_EVAL_UNAVAILABLE (SPEC 10.1 step 7.6).
+     */
+    value?: {
         type: string;
         value: string | boolean;
     };
@@ -40,7 +57,9 @@ declare class Stop extends Error {
 /**
  * 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. With
+ * {keyId: publicKeyHex} map, or an array of these. With `recompute`, step 7 runs too; without
+ * its `value`, steps 7.1-7.5 run and the result is success at level "signed" with code
+ * E_EVAL_UNAVAILABLE (path "$.value") unless they fail. 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.

package/dist/esm/verify.js

@@ -63,11 +63,12 @@ function verifySigned(input, sources, setHash) {
     }
     return { receipt, hash };
 }
+/** Step 7. Throws Stop; returns false when 7.6 could not run (no value: E_EVAL_UNAVAILABLE). */
 function recompute(receipt, rc, sources) {
     const cell = receipt.cell;
     const cellArgs = cell.args;
-    // 7.1 Descriptor.
-    if (rc.descriptor === undefined || rc.descriptor === null)
+    // 7.1 Descriptor. Only obtaining nothing is unavailability; null is a descriptor offered (D35).
+    if (rc.descriptor === undefined)
         stop('E_FN_UNAVAILABLE', `no descriptor for ${cell.fn_hash}`, '$.cell.fn_hash');
     let desc;
     try {
@@ -130,18 +131,23 @@ function recompute(receipt, rc, sources) {
         if (!declaredInputs.includes(`${ic.ns}/${ic.fn}`)) {
             stop('E_INPUT_UNDECLARED', `input ${h} is a cell of an undeclared function`, '$.inputs');
         }
-        if (inner.receipt.asof !== receipt.asof)
-            stop('E_TIME_ORDER', "input receipts must share the receipt's asof", '$.inputs');
+        // At or before the receipt's asof (D17, revised in spec-0.3.0); instants are fixed width, so
+        // string order is time order (SPEC 3.3).
+        if (!(inner.receipt.asof <= receipt.asof))
+            stop('E_TIME_ORDER', `input ${h} has asof ${inner.receipt.asof}, after the receipt's asof`, '$.inputs');
         const itx = inner.receipt.tx;
         if (latestTx === null || itx > latestTx)
             latestTx = itx;
     }
     if (latestTx !== null && receipt.tx !== latestTx)
         stop('E_TIME_ORDER', 'tx must be the latest input tx', '$.tx');
-    // 7.6 Value.
+    // 7.6 Value. No value: the function could not be evaluated (E_EVAL_UNAVAILABLE, not a failure).
     const v = rc.value;
+    if (v === undefined)
+        return false;
     if (v.type !== receipt.type || v.value !== receipt.value)
         stop('E_VALUE_MISMATCH', 'recomputed value differs from the receipt', '$.value');
+    return true;
 }
 /**
  * Step 7.7: content is only for a blob value (E_SCHEMA otherwise); it has exactly `length`
@@ -171,8 +177,8 @@ function checkRecomputeArg(rc) {
     if (typeof rc !== 'object' || Array.isArray(rc))
         throw new TypeError('recompute must be an object {descriptor, inputs, value}');
     const r = rc;
-    if (!r.value || typeof r.value !== 'object' || typeof r.value.type !== 'string' || (typeof r.value.value !== 'string' && typeof r.value.value !== 'boolean')) {
-        throw new TypeError('recompute.value must be the evaluated typed scalar {type, value}');
+    if (r.value !== undefined && (!r.value || typeof r.value !== 'object' || typeof r.value.type !== 'string' || (typeof r.value.value !== 'string' && typeof r.value.value !== 'boolean'))) {
+        throw new TypeError('recompute.value must be the evaluated typed scalar {type, value}, or absent when the function could not be evaluated');
     }
     if (r.inputs !== undefined && (typeof r.inputs !== 'object' || r.inputs === null || Array.isArray(r.inputs))) {
         throw new TypeError('recompute.inputs must be an object mapping receipt hash to receipt JSON');
@@ -182,7 +188,9 @@ 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. With
+ * {keyId: publicKeyHex} map, or an array of these. With `recompute`, step 7 runs too; without
+ * its `value`, steps 7.1-7.5 run and the result is success at level "signed" with code
+ * E_EVAL_UNAVAILABLE (path "$.value") unless they fail. 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.
@@ -197,20 +205,24 @@ export function verify(receipt, keys, recomputeArg, blob) {
     let hash = null;
     try {
         const { receipt: r } = verifySigned(receipt, sources, (h) => (hash = h));
-        if (rc)
-            recompute(r, rc, sources);
+        const evaluated = rc ? recompute(r, rc, sources) : false;
         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}`;
+            checkContent(r, content); // 7.7 also after E_EVAL_UNAVAILABLE; its failure replaces the code
+        const unavailable = rc !== null && !evaluated;
+        const what = evaluated
+            ? 'fully verified: signature valid and value recomputed'
+            : unavailable
+                ? `signature-valid: signed by ${r.computed_by}; descriptor, arguments and inputs check out, but the function could not be evaluated, so the value was not recomputed`
+                : `signature-valid: signed by ${r.computed_by}`;
         return {
             ok: true,
-            code: 'OK',
-            level: rc ? 'recomputed' : 'signed',
+            code: unavailable ? 'E_EVAL_UNAVAILABLE' : 'OK',
+            level: evaluated ? 'recomputed' : 'signed',
             hash,
             key: r.computed_by,
             detail: checked ? `${what}; blob content matches` : what,
-            path: null,
+            path: unavailable ? '$.value' : null,
             blobChecked: checked,
         };
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@datumesh/verify",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "Verifier for Datumesh receipts: strict canonical JSON (RFC 8785), cell URIs, units, blobs, response envelopes, key documents and Ed25519 signatures.",
   "license": "Apache-2.0",
   "repository": {
@@ -10,7 +10,7 @@
   "homepage": "https://datumesh.com",
   "keywords": ["datumesh", "receipt", "verify", "ed25519", "jcs", "rfc8785", "canonical-json"],
   "datumesh": {
-    "spec": "spec-0.2.1"
+    "spec": "spec-0.3.0"
   },
   "type": "module",
   "main": "./dist/cjs/index.js",