@blue-quickjs/quickjs-runtime 0.1.0

package/dist/lib/evaluate.js

@@ -0,0 +1,284 @@
+import { DV_LIMIT_DEFAULTS, decodeDv, } from '@blue-quickjs/dv';
+import { initializeDeterministicVm } from './deterministic-init.js';
+import { validateInputEnvelope, validateProgramArtifact, } from './quickjs-runtime.js';
+import { createRuntime, } from './runtime.js';
+import { createInvalidOutputError, mapVmError, } from './evaluate-errors.js';
+import { parseHexToBytes } from './hex-utils.js';
+const HOST_TAPE_MAX_CAPACITY = 1024;
+export async function evaluate(options) {
+    const program = validateProgramArtifact(options.program);
+    const input = validateInputEnvelope(options.input, options.inputValidation);
+    const runtime = await createRuntime({
+        manifest: options.manifest,
+        handlers: options.handlers,
+        variant: options.variant,
+        buildType: options.buildType,
+        metadata: options.metadata,
+        wasmBinary: options.wasmBinary,
+        dvLimits: options.dvLimits,
+        expectedAbiId: program.abiId,
+        expectedAbiVersion: program.abiVersion,
+    });
+    assertEngineBuildHash(program, runtime);
+    const vm = initializeDeterministicVm(runtime, program, input, options.gasLimit);
+    if (options.tape) {
+        const capacity = options.tape.capacity ?? 128;
+        if (!Number.isInteger(capacity) || capacity < 0) {
+            throw new Error('tape capacity must be a non-negative integer');
+        }
+        if (capacity > HOST_TAPE_MAX_CAPACITY) {
+            throw new Error(`tape capacity exceeds max (${HOST_TAPE_MAX_CAPACITY}); received ${capacity}`);
+        }
+        vm.enableTape(capacity);
+    }
+    if (options.gasTrace) {
+        vm.enableGasTrace(true);
+    }
+    try {
+        const raw = vm.eval(program.code);
+        const parsed = parseEvalOutput(raw);
+        const tape = options.tape ? parseTape(vm.readTape()) : undefined;
+        const trace = options.gasTrace
+            ? parseGasTrace(vm.readGasTrace())
+            : undefined;
+        if (parsed.kind === 'error') {
+            const error = mapVmError(parsed.payload, runtime.manifest);
+            return {
+                ok: false,
+                type: 'vm-error',
+                message: error.message,
+                error,
+                gasUsed: parsed.gasUsed,
+                gasRemaining: parsed.gasRemaining,
+                raw,
+                tape,
+                gasTrace: trace,
+            };
+        }
+        const decoded = decodeResultPayload(parsed.payload, options.outputDvLimits);
+        if (decoded.kind === 'error') {
+            const error = createInvalidOutputError(decoded.message, decoded.cause);
+            return {
+                ok: false,
+                type: 'invalid-output',
+                message: error.message,
+                error,
+                gasUsed: parsed.gasUsed,
+                gasRemaining: parsed.gasRemaining,
+                raw,
+                tape,
+                gasTrace: trace,
+            };
+        }
+        return {
+            ok: true,
+            value: decoded.value,
+            gasUsed: parsed.gasUsed,
+            gasRemaining: parsed.gasRemaining,
+            raw,
+            tape,
+            gasTrace: trace,
+        };
+    }
+    finally {
+        vm.dispose();
+    }
+}
+function parseEvalOutput(raw) {
+    const normalized = raw.trim();
+    let kind;
+    if (normalized.startsWith('RESULT')) {
+        kind = 'RESULT';
+    }
+    else if (normalized.startsWith('ERROR')) {
+        kind = 'ERROR';
+    }
+    else {
+        throw new Error(`Unexpected VM output prefix: ${normalized}`);
+    }
+    const withoutKind = normalized.slice(kind.length).trimStart();
+    const trailerMarker = ' GAS remaining=';
+    const usedMarker = ' used=';
+    const trailerIdx = withoutKind.lastIndexOf(trailerMarker);
+    if (trailerIdx < 0) {
+        throw new Error(`Missing gas trailer in VM output: ${normalized}`);
+    }
+    const payload = withoutKind.slice(0, trailerIdx).trimEnd();
+    const trailer = withoutKind.slice(trailerIdx + trailerMarker.length);
+    const usedIdx = trailer.lastIndexOf(usedMarker);
+    if (usedIdx < 0) {
+        throw new Error(`Missing used= trailer in VM output: ${normalized}`);
+    }
+    const remainingStr = trailer.slice(0, usedIdx).trim();
+    const usedStr = trailer.slice(usedIdx + usedMarker.length).trim();
+    return {
+        kind: kind === 'RESULT' ? 'result' : 'error',
+        payload,
+        gasRemaining: parseUint64(remainingStr, 'gasRemaining'),
+        gasUsed: parseUint64(usedStr, 'gasUsed'),
+    };
+}
+function decodeResultPayload(payload, limits) {
+    const dvLimits = normalizeDvLimits(limits);
+    let bytes;
+    try {
+        bytes = parseHexToBytes(payload, dvLimits.maxEncodedBytes);
+    }
+    catch (err) {
+        return {
+            kind: 'error',
+            message: `VM returned non-hex DV payload: ${err instanceof Error ? err.message : String(err)}`,
+            cause: err,
+        };
+    }
+    try {
+        const value = decodeDv(bytes, { limits: dvLimits });
+        return { kind: 'ok', value };
+    }
+    catch (err) {
+        return {
+            kind: 'error',
+            message: `VM returned non-DV value: ${err instanceof Error ? err.message : String(err)}`,
+            cause: err,
+        };
+    }
+}
+function parseTape(raw) {
+    const parsed = parseJson(raw, 'tape');
+    if (!Array.isArray(parsed)) {
+        throw new Error('tape payload is not an array');
+    }
+    return parsed.map((record, idx) => {
+        if (record === null || typeof record !== 'object') {
+            throw new Error(`tape record ${idx} is not an object`);
+        }
+        const fnId = expectUint32(record.fnId, `tape[${idx}].fnId`);
+        const reqLen = expectUint32(record.reqLen, `tape[${idx}].reqLen`);
+        const respLen = expectUint32(record.respLen, `tape[${idx}].respLen`);
+        const units = expectUint32(record.units, `tape[${idx}].units`);
+        const gasPre = expectBigIntString(record.gasPre, `tape[${idx}].gasPre`);
+        const gasPost = expectBigIntString(record.gasPost, `tape[${idx}].gasPost`);
+        const isError = Boolean(record.isError);
+        const chargeFailed = Boolean(record.chargeFailed);
+        const reqHash = expectHex(record.reqHash, `tape[${idx}].reqHash`, 64);
+        const respHash = expectHex(record.respHash, `tape[${idx}].respHash`, 64);
+        return {
+            fnId,
+            reqLen,
+            respLen,
+            units,
+            gasPre,
+            gasPost,
+            isError,
+            chargeFailed,
+            reqHash,
+            respHash,
+        };
+    });
+}
+function parseGasTrace(raw) {
+    const obj = expectRecord(parseJson(raw, 'gasTrace'), 'gasTrace');
+    return {
+        opcodeCount: expectBigIntString(obj.opcodeCount, 'gasTrace.opcodeCount'),
+        opcodeGas: expectBigIntString(obj.opcodeGas, 'gasTrace.opcodeGas'),
+        arrayCbBaseCount: expectBigIntString(obj.arrayCbBaseCount, 'gasTrace.arrayCbBaseCount'),
+        arrayCbBaseGas: expectBigIntString(obj.arrayCbBaseGas, 'gasTrace.arrayCbBaseGas'),
+        arrayCbPerElCount: expectBigIntString(obj.arrayCbPerElCount, 'gasTrace.arrayCbPerElCount'),
+        arrayCbPerElGas: expectBigIntString(obj.arrayCbPerElGas, 'gasTrace.arrayCbPerElGas'),
+        allocationCount: expectBigIntString(obj.allocationCount, 'gasTrace.allocationCount'),
+        allocationBytes: expectBigIntString(obj.allocationBytes, 'gasTrace.allocationBytes'),
+        allocationGas: expectBigIntString(obj.allocationGas, 'gasTrace.allocationGas'),
+    };
+}
+function parseJson(raw, label) {
+    try {
+        return JSON.parse(raw);
+    }
+    catch (err) {
+        throw new Error(`${label} payload is not valid JSON: ${err instanceof Error ? err.message : String(err)}`);
+    }
+}
+function expectUint32(value, path) {
+    if (typeof value !== 'number' || !Number.isInteger(value) || value < 0) {
+        throw new Error(`${path} must be a non-negative integer`);
+    }
+    if (value > 0xffffffff) {
+        throw new Error(`${path} exceeds uint32`);
+    }
+    return value;
+}
+function expectBigIntString(value, path) {
+    if (typeof value === 'bigint') {
+        if (value < 0n) {
+            throw new Error(`${path} must be non-negative`);
+        }
+        return value;
+    }
+    if (typeof value !== 'string') {
+        throw new Error(`${path} must be a string`);
+    }
+    try {
+        const parsed = BigInt(value);
+        if (parsed < 0n) {
+            throw new Error(`${path} must be non-negative`);
+        }
+        return parsed;
+    }
+    catch (err) {
+        throw new Error(`${path} is not a valid bigint string: ${err instanceof Error ? err.message : String(err)}`);
+    }
+}
+function expectHex(value, path, length) {
+    if (typeof value !== 'string') {
+        throw new Error(`${path} must be a hex string`);
+    }
+    if (value.length !== length) {
+        throw new Error(`${path} must be ${length} hex characters`);
+    }
+    if (!/^[0-9a-f]+$/.test(value)) {
+        throw new Error(`${path} must be lowercase hex`);
+    }
+    return value;
+}
+function expectRecord(value, path) {
+    if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+        throw new Error(`${path} payload is not an object`);
+    }
+    return value;
+}
+function normalizeDvLimits(overrides) {
+    return {
+        maxDepth: overrides?.maxDepth ?? DV_LIMIT_DEFAULTS.maxDepth,
+        maxEncodedBytes: overrides?.maxEncodedBytes ?? DV_LIMIT_DEFAULTS.maxEncodedBytes,
+        maxStringBytes: overrides?.maxStringBytes ?? DV_LIMIT_DEFAULTS.maxStringBytes,
+        maxArrayLength: overrides?.maxArrayLength ?? DV_LIMIT_DEFAULTS.maxArrayLength,
+        maxMapLength: overrides?.maxMapLength ?? DV_LIMIT_DEFAULTS.maxMapLength,
+    };
+}
+function parseUint64(text, label) {
+    try {
+        const value = BigInt(text);
+        if (value < 0n) {
+            throw new Error(`${label} must be non-negative`);
+        }
+        return value;
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : `Invalid ${label} value`;
+        throw new Error(`${message}: ${text}`);
+    }
+}
+function assertEngineBuildHash(program, runtime) {
+    if (!program.engineBuildHash) {
+        return;
+    }
+    const runtimeHash = runtime.artifact.variantMetadata.engineBuildHash ??
+        runtime.metadata.engineBuildHash ??
+        null;
+    if (!runtimeHash) {
+        throw new Error('Engine build hash is unavailable; cannot verify program.engineBuildHash');
+    }
+    if (runtimeHash !== program.engineBuildHash) {
+        throw new Error(`engineBuildHash mismatch: program=${program.engineBuildHash} runtime=${runtimeHash}`);
+    }
+}

package/dist/lib/hex-utils.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Parse a lowercase hex string into a byte array with optional max-length enforcement.
+ */
+export declare function parseHexToBytes(payload: string, maxBytes?: number): Uint8Array;
+//# sourceMappingURL=hex-utils.d.ts.map

package/dist/lib/hex-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hex-utils.d.ts","sourceRoot":"","sources":["../../src/lib/hex-utils.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,wBAAgB,eAAe,CAC7B,OAAO,EAAE,MAAM,EACf,QAAQ,CAAC,EAAE,MAAM,GAChB,UAAU,CAsBZ"}

package/dist/lib/hex-utils.js

@@ -0,0 +1,24 @@
+/**
+ * Parse a lowercase hex string into a byte array with optional max-length enforcement.
+ */
+export function parseHexToBytes(payload, maxBytes) {
+    const normalized = payload.trim();
+    if (normalized.length === 0) {
+        throw new Error('payload is empty');
+    }
+    if (normalized.length % 2 !== 0) {
+        throw new Error('payload length is not even');
+    }
+    if (!/^[0-9a-f]+$/.test(normalized)) {
+        throw new Error('payload is not lowercase hex');
+    }
+    const byteLength = normalized.length / 2;
+    if (maxBytes !== undefined && byteLength > maxBytes) {
+        throw new Error(`payload exceeds maxBytes (${byteLength} > ${maxBytes})`);
+    }
+    const bytes = new Uint8Array(byteLength);
+    for (let i = 0; i < normalized.length; i += 2) {
+        bytes[i / 2] = parseInt(normalized.slice(i, i + 2), 16);
+    }
+    return bytes;
+}

package/dist/lib/host-dispatcher.d.ts

@@ -0,0 +1,62 @@
+import { type AbiManifest, type CanonicalAbiManifest } from '@blue-quickjs/abi-manifest';
+import { type DV, type DvLimits } from '@blue-quickjs/dv';
+export interface HostCallError {
+    code: string;
+    tag: string;
+    details?: DV;
+}
+export type HostCallResult<T extends DV | null = DV> = {
+    ok: T;
+    units: number;
+} | {
+    err: HostCallError;
+    units: number;
+};
+export interface DocumentHostHandlers {
+    get(path: string): HostCallResult<DV>;
+    getCanonical(path: string): HostCallResult<DV>;
+}
+export interface EmitHostHandler {
+    emit(value: DV): HostCallResult<null>;
+}
+export interface HostDispatcherHandlers {
+    document: DocumentHostHandlers;
+    emit?: EmitHostHandler['emit'];
+}
+export interface HostDispatcherOptions {
+    /**
+     * Override DV limits applied to request decoding and response encoding.
+     */
+    dvLimits?: Partial<DvLimits>;
+    /**
+     * Enforce a specific ABI identity (defaults to Host.v1) to avoid pairing the
+     * dispatcher with a mismatched manifest.
+     */
+    expectedAbiId?: string;
+    expectedAbiVersion?: number;
+}
+export type HostDispatchResult = {
+    kind: 'response';
+    envelope: Uint8Array;
+} | {
+    kind: 'fatal';
+    error: HostDispatcherError;
+};
+export type HostDispatcherErrorCode = 'UNKNOWN_FUNCTION' | 'INVALID_REQUEST' | 'INVALID_ARGUMENTS' | 'HANDLER_ERROR' | 'RESPONSE_LIMIT';
+export declare class HostDispatcherError extends Error {
+    readonly code: HostDispatcherErrorCode;
+    constructor(code: HostDispatcherErrorCode, message: string, options?: {
+        cause?: unknown;
+    });
+}
+export interface HostDispatcher {
+    readonly manifest: CanonicalAbiManifest;
+    dispatch(fnId: number, requestBytes: ArrayBufferView | ArrayBuffer): HostDispatchResult;
+}
+export interface HostCallMemory {
+    buffer: ArrayBuffer;
+}
+export type HostCallImport = (fnId: number, reqPtr: number, reqLen: number, respPtr: number, respCap: number) => number;
+export declare function createHostDispatcher(manifest: AbiManifest, handlers: HostDispatcherHandlers, options?: HostDispatcherOptions): HostDispatcher;
+export declare function createHostCallImport(dispatcher: HostDispatcher, memory: HostCallMemory): HostCallImport;
+//# sourceMappingURL=host-dispatcher.d.ts.map

package/dist/lib/host-dispatcher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"host-dispatcher.d.ts","sourceRoot":"","sources":["../../src/lib/host-dispatcher.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,WAAW,EAChB,KAAK,oBAAoB,EAE1B,MAAM,4BAA4B,CAAC;AACpC,OAAO,EACL,KAAK,EAAE,EAEP,KAAK,QAAQ,EAKd,MAAM,kBAAkB,CAAC;AAK1B,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,CAAC,EAAE,EAAE,CAAC;CACd;AAED,MAAM,MAAM,cAAc,CAAC,CAAC,SAAS,EAAE,GAAG,IAAI,GAAG,EAAE,IAC/C;IAAE,EAAE,EAAE,CAAC,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GACxB;IAAE,GAAG,EAAE,aAAa,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAE1C,MAAM,WAAW,oBAAoB;IACnC,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,cAAc,CAAC,EAAE,CAAC,CAAC;IACtC,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,cAAc,CAAC,EAAE,CAAC,CAAC;CAChD;AAED,MAAM,WAAW,eAAe;IAC9B,IAAI,CAAC,KAAK,EAAE,EAAE,GAAG,cAAc,CAAC,IAAI,CAAC,CAAC;CACvC;AAED,MAAM,WAAW,sBAAsB;IACrC,QAAQ,EAAE,oBAAoB,CAAC;IAC/B,IAAI,CAAC,EAAE,eAAe,CAAC,MAAM,CAAC,CAAC;CAChC;AAED,MAAM,WAAW,qBAAqB;IACpC;;OAEG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC,QAAQ,CAAC,CAAC;IAC7B;;;OAGG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,kBAAkB,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED,MAAM,MAAM,kBAAkB,GAC1B;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,QAAQ,EAAE,UAAU,CAAA;CAAE,GAC1C;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,mBAAmB,CAAA;CAAE,CAAC;AAElD,MAAM,MAAM,uBAAuB,GAC/B,kBAAkB,GAClB,iBAAiB,GACjB,mBAAmB,GACnB,eAAe,GACf,gBAAgB,CAAC;AAErB,qBAAa,mBAAoB,SAAQ,KAAK;aAE1B,IAAI,EAAE,uBAAuB;gBAA7B,IAAI,EAAE,uBAAuB,EAC7C,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE;CAKhC;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,QAAQ,EAAE,oBAAoB,CAAC;IACxC,QAAQ,CACN,IAAI,EAAE,MAAM,EACZ,YAAY,EAAE,eAAe,GAAG,WAAW,GAC1C,kBAAkB,CAAC;CACvB;AAED,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,WAAW,CAAC;CACrB;AAED,MAAM,MAAM,cAAc,GAAG,CAC3B,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,MAAM,KACZ,MAAM,CAAC;AAEZ,wBAAgB,oBAAoB,CAClC,QAAQ,EAAE,WAAW,EACrB,QAAQ,EAAE,sBAAsB,EAChC,OAAO,CAAC,EAAE,qBAAqB,GAC9B,cAAc,CAuFhB;AAED,wBAAgB,oBAAoB,CAClC,UAAU,EAAE,cAAc,EAC1B,MAAM,EAAE,cAAc,GACrB,cAAc,CA6ChB"}