@blue-quickjs/quickjs-runtime 0.1.0

package/dist/lib/host-dispatcher.js

@@ -0,0 +1,397 @@
+import { validateAbiManifest, } from '@blue-quickjs/abi-manifest';
+import { DV_LIMIT_DEFAULTS, DvError, decodeDv, encodeDv, validateDv, } from '@blue-quickjs/dv';
+const UINT32_MAX = 0xffffffff;
+const UTF8 = new TextEncoder();
+export class HostDispatcherError extends Error {
+    code;
+    constructor(code, message, options) {
+        super(message, options);
+        this.code = code;
+        this.name = 'HostDispatcherError';
+    }
+}
+export function createHostDispatcher(manifest, handlers, options) {
+    const canonical = validateAbiManifest(manifest);
+    const expectedAbiId = options?.expectedAbiId ?? 'Host.v1';
+    const expectedAbiVersion = options?.expectedAbiVersion ?? 1;
+    if (canonical.abi_id !== expectedAbiId) {
+        throw new HostDispatcherError('INVALID_REQUEST', `manifest abi_id mismatch: expected ${expectedAbiId}, received ${canonical.abi_id}`);
+    }
+    if (canonical.abi_version !== expectedAbiVersion) {
+        throw new HostDispatcherError('INVALID_REQUEST', `manifest abi_version mismatch: expected ${expectedAbiVersion}, received ${canonical.abi_version}`);
+    }
+    const dvLimits = normalizeDvLimits(options?.dvLimits);
+    const bindings = buildBindings(canonical.functions, handlers);
+    return {
+        manifest: canonical,
+        dispatch(fnId, requestBytes) {
+            const normalizedFnId = toUint32(fnId);
+            const binding = bindings.get(normalizedFnId);
+            if (!binding) {
+                return fatal('UNKNOWN_FUNCTION', `unknown fn_id ${normalizedFnId}`);
+            }
+            const request = asUint8Array(requestBytes);
+            if (request.length > binding.fn.limits.max_request_bytes) {
+                if (binding.limitExceededEnvelope) {
+                    return encodeEnvelope(binding.fn, binding.limitExceededEnvelope, dvLimits);
+                }
+                return fatalLimitError(binding.fn);
+            }
+            const decodeLimits = {
+                ...dvLimits,
+                maxEncodedBytes: Math.min(dvLimits.maxEncodedBytes, binding.fn.limits.max_request_bytes),
+            };
+            let args;
+            try {
+                args = decodeDv(request, { limits: decodeLimits });
+            }
+            catch (err) {
+                return fatal('INVALID_REQUEST', `failed to decode request for fn_id=${normalizedFnId}: ${stringifyError(err)}`, err);
+            }
+            if (!Array.isArray(args)) {
+                return fatal('INVALID_ARGUMENTS', `request for fn_id=${normalizedFnId} must be a DV array`);
+            }
+            if (args.length !== binding.fn.arity) {
+                return fatal('INVALID_ARGUMENTS', `fn_id=${normalizedFnId} expected ${binding.fn.arity} args, received ${args.length}`);
+            }
+            try {
+                return binding.dispatch(args, dvLimits);
+            }
+            catch (err) {
+                return fatal('HANDLER_ERROR', `fn_id=${normalizedFnId} handler threw: ${stringifyError(err)}`, err);
+            }
+        },
+    };
+}
+export function createHostCallImport(dispatcher, memory) {
+    let inProgress = false;
+    return (fnId, reqPtr, reqLen, respPtr, respCap) => {
+        if (inProgress) {
+            return UINT32_MAX;
+        }
+        inProgress = true;
+        try {
+            const mem = new Uint8Array(memory.buffer);
+            const reqOffset = toUint32(reqPtr);
+            const reqLength = toUint32(reqLen);
+            const respOffset = toUint32(respPtr);
+            const respCapacity = toUint32(respCap);
+            const fn = toUint32(fnId);
+            if (!withinBounds(mem, reqOffset, reqLength) ||
+                !withinBounds(mem, respOffset, respCapacity)) {
+                return UINT32_MAX;
+            }
+            if (rangesOverlap(reqOffset, reqLength, respOffset, respCapacity)) {
+                return UINT32_MAX;
+            }
+            const request = mem.subarray(reqOffset, reqOffset + reqLength);
+            const result = dispatcher.dispatch(fn, request);
+            if (result.kind === 'fatal') {
+                return UINT32_MAX;
+            }
+            if (result.envelope.length > respCapacity) {
+                return UINT32_MAX;
+            }
+            mem
+                .subarray(respOffset, respOffset + result.envelope.length)
+                .set(result.envelope);
+            return result.envelope.length >>> 0;
+        }
+        catch {
+            return UINT32_MAX;
+        }
+        finally {
+            inProgress = false;
+        }
+    };
+}
+function buildBindings(functions, handlers) {
+    const bindings = new Map();
+    const byPath = new Map();
+    for (const fn of functions) {
+        const canonical = withErrorTags(fn);
+        byPath.set(canonical.js_path.join('.'), canonical);
+    }
+    const documentGet = byPath.get('document.get');
+    const documentGetCanonical = byPath.get('document.getCanonical');
+    if (!documentGet || !documentGetCanonical) {
+        throw new HostDispatcherError('INVALID_REQUEST', 'Host.v1 manifest must include document.get and document.getCanonical');
+    }
+    const emitFn = byPath.get('emit');
+    if (emitFn && !handlers.emit) {
+        throw new HostDispatcherError('INVALID_REQUEST', 'manifest declares emit but no emit handler was provided');
+    }
+    if (!emitFn && handlers.emit) {
+        throw new HostDispatcherError('INVALID_REQUEST', 'emit handler provided but manifest does not declare emit');
+    }
+    bindings.set(documentGet.fn_id, buildDocumentBinding(documentGet, handlers.document.get));
+    bindings.set(documentGetCanonical.fn_id, buildDocumentBinding(documentGetCanonical, handlers.document.getCanonical));
+    if (emitFn && handlers.emit) {
+        bindings.set(emitFn.fn_id, buildEmitBinding(emitFn, handlers.emit));
+    }
+    if (functions.length !== bindings.size) {
+        const knownIds = [...bindings.keys()].sort((a, b) => a - b).join(', ');
+        const manifestIds = functions.map((fn) => fn.fn_id).sort((a, b) => a - b);
+        throw new HostDispatcherError('INVALID_REQUEST', `dispatcher does not implement all manifest functions (implemented: ${knownIds}; manifest: ${manifestIds.join(', ')})`);
+    }
+    return bindings;
+}
+function buildDocumentBinding(fn, handler) {
+    assertDocumentShape(fn);
+    const limitExceededEnvelope = createLimitEnvelope(fn);
+    return {
+        fn,
+        limitExceededEnvelope,
+        dispatch(args, dvLimits) {
+            const [path] = args;
+            if (typeof path !== 'string') {
+                return fatal('INVALID_ARGUMENTS', `fn_id=${fn.fn_id} expected string path argument`);
+            }
+            const utf8Max = fn.limits.arg_utf8_max?.[0];
+            if (utf8Max !== undefined) {
+                const byteLen = UTF8.encode(path).byteLength;
+                if (byteLen > utf8Max) {
+                    if (limitExceededEnvelope) {
+                        return encodeEnvelope(fn, limitExceededEnvelope, dvLimits);
+                    }
+                    return fatal('INVALID_ARGUMENTS', `fn_id=${fn.fn_id} path exceeds utf8 limit (${byteLen} > ${utf8Max})`);
+                }
+            }
+            const result = handler(path);
+            return encodeResult(fn, result, dvLimits, limitExceededEnvelope);
+        },
+    };
+}
+function buildEmitBinding(fn, handler) {
+    assertEmitShape(fn);
+    const limitExceededEnvelope = createLimitEnvelope(fn);
+    return {
+        fn,
+        limitExceededEnvelope,
+        dispatch(args, dvLimits) {
+            const [value] = args;
+            const result = handler(value);
+            return encodeResult(fn, result, dvLimits, limitExceededEnvelope);
+        },
+    };
+}
+function encodeResult(fn, result, dvLimits, limitExceededEnvelope) {
+    if (result === null || typeof result !== 'object') {
+        return fatal('HANDLER_ERROR', `fn_id=${fn.fn_id} returned invalid result`);
+    }
+    const hasOk = 'ok' in result;
+    const hasErr = 'err' in result;
+    if (hasOk === hasErr) {
+        return fatal('HANDLER_ERROR', `fn_id=${fn.fn_id} result must contain exactly one of ok or err`);
+    }
+    if (!('units' in result)) {
+        return fatal('HANDLER_ERROR', `fn_id=${fn.fn_id} result.units is required`);
+    }
+    let units;
+    try {
+        units = normalizeUint(result.units, fn.limits.max_units, 'result.units', !!limitExceededEnvelope);
+    }
+    catch (err) {
+        if (err instanceof HostDispatcherError) {
+            return fatal(err.code, err.message, err);
+        }
+        throw err;
+    }
+    if (units === null) {
+        if (limitExceededEnvelope) {
+            return encodeEnvelope(fn, limitExceededEnvelope, dvLimits);
+        }
+        return fatal('INVALID_ARGUMENTS', `fn_id=${fn.fn_id} units exceed max_units (${fn.limits.max_units})`);
+    }
+    if ('ok' in result) {
+        if (fn.return_schema.type === 'null' && result.ok !== null) {
+            return fatal('HANDLER_ERROR', `fn_id=${fn.fn_id} must return null for return_schema "null"`);
+        }
+        if (fn.return_schema.type === 'dv') {
+            try {
+                validateDv(result.ok, {
+                    limits: cappedDvLimits(dvLimits, fn.limits.max_response_bytes),
+                });
+            }
+            catch (err) {
+                return handleDvValidationError(fn, err, limitExceededEnvelope, dvLimits);
+            }
+        }
+        return encodeEnvelope(fn, { ok: result.ok, units }, dvLimits, limitExceededEnvelope);
+    }
+    if (result.err === null ||
+        typeof result.err !== 'object' ||
+        typeof result.err.code !== 'string' ||
+        typeof result.err.tag !== 'string') {
+        return fatal('HANDLER_ERROR', `fn_id=${fn.fn_id} returned malformed err payload`);
+    }
+    const manifestTag = fn.errorTagMap.get(result.err.code);
+    if (!manifestTag) {
+        return fatal('HANDLER_ERROR', `fn_id=${fn.fn_id} returned unknown error code ${result.err.code}`);
+    }
+    if (result.err.tag !== manifestTag) {
+        return fatal('HANDLER_ERROR', `fn_id=${fn.fn_id} error tag mismatch for code ${result.err.code}: expected ${manifestTag}, received ${result.err.tag}`);
+    }
+    if (result.err.details !== undefined) {
+        try {
+            validateDv(result.err.details, {
+                limits: cappedDvLimits(dvLimits, fn.limits.max_response_bytes),
+            });
+        }
+        catch (err) {
+            return handleDvValidationError(fn, err, limitExceededEnvelope, dvLimits);
+        }
+    }
+    return encodeEnvelope(fn, {
+        err: result.err.details === undefined
+            ? { code: result.err.code }
+            : { code: result.err.code, details: result.err.details },
+        units,
+    }, dvLimits, limitExceededEnvelope);
+}
+function encodeEnvelope(fn, envelope, dvLimits, limitExceededEnvelope) {
+    const encodeLimits = cappedDvLimits(dvLimits, fn.limits.max_response_bytes);
+    try {
+        const bytes = encodeDv(envelope, { limits: encodeLimits });
+        return { kind: 'response', envelope: bytes };
+    }
+    catch (err) {
+        if (limitExceededEnvelope && isSizeRelatedDvError(err)) {
+            try {
+                const bytes = encodeDv(limitExceededEnvelope, { limits: encodeLimits });
+                return { kind: 'response', envelope: bytes };
+            }
+            catch (limitErr) {
+                return fatal('RESPONSE_LIMIT', `fn_id=${fn.fn_id} failed to encode limit response: ${stringifyError(limitErr)}`, limitErr);
+            }
+        }
+        return fatal('RESPONSE_LIMIT', `fn_id=${fn.fn_id} failed to encode response: ${stringifyError(err)}`, err);
+    }
+}
+function createLimitEnvelope(fn) {
+    if (!fn.errorTagMap.has('LIMIT_EXCEEDED')) {
+        return undefined;
+    }
+    return { err: { code: 'LIMIT_EXCEEDED' }, units: 0 };
+}
+function assertDocumentShape(fn) {
+    if (fn.arity !== 1 || fn.arg_schema.length !== 1) {
+        throw new HostDispatcherError('INVALID_REQUEST', `document.* functions must have arity 1 (fn_id=${fn.fn_id})`);
+    }
+    if (fn.arg_schema[0]?.type !== 'string') {
+        throw new HostDispatcherError('INVALID_REQUEST', `document.* functions must take a string argument (fn_id=${fn.fn_id})`);
+    }
+    if (fn.return_schema.type !== 'dv') {
+        throw new HostDispatcherError('INVALID_REQUEST', `document.* functions must return DV (fn_id=${fn.fn_id})`);
+    }
+}
+function assertEmitShape(fn) {
+    if (fn.arity !== 1 || fn.arg_schema.length !== 1) {
+        throw new HostDispatcherError('INVALID_REQUEST', `emit must have arity 1 (fn_id=${fn.fn_id})`);
+    }
+    if (fn.arg_schema[0]?.type !== 'dv') {
+        throw new HostDispatcherError('INVALID_REQUEST', `emit must take a DV argument (fn_id=${fn.fn_id})`);
+    }
+    if (fn.return_schema.type !== 'null') {
+        throw new HostDispatcherError('INVALID_REQUEST', `emit must return null (fn_id=${fn.fn_id})`);
+    }
+}
+function handleDvValidationError(fn, err, limitExceededEnvelope, dvLimits) {
+    if (limitExceededEnvelope && isSizeRelatedDvError(err)) {
+        return encodeEnvelope(fn, limitExceededEnvelope, dvLimits);
+    }
+    return fatal('HANDLER_ERROR', `fn_id=${fn.fn_id} produced non-DV value: ${stringifyError(err)}`, err);
+}
+function cappedDvLimits(limits, maxBytes) {
+    return {
+        ...limits,
+        maxEncodedBytes: Math.min(limits.maxEncodedBytes, maxBytes),
+    };
+}
+function normalizeDvLimits(limits) {
+    return {
+        maxDepth: limits?.maxDepth ?? DV_LIMIT_DEFAULTS.maxDepth,
+        maxEncodedBytes: limits?.maxEncodedBytes ?? DV_LIMIT_DEFAULTS.maxEncodedBytes,
+        maxStringBytes: limits?.maxStringBytes ?? DV_LIMIT_DEFAULTS.maxStringBytes,
+        maxArrayLength: limits?.maxArrayLength ?? DV_LIMIT_DEFAULTS.maxArrayLength,
+        maxMapLength: limits?.maxMapLength ?? DV_LIMIT_DEFAULTS.maxMapLength,
+    };
+}
+function toUint32(value) {
+    if (typeof value !== 'number' || !Number.isInteger(value)) {
+        return 0;
+    }
+    return value >>> 0;
+}
+function normalizeUint(value, max, path, allowOverflow) {
+    if (typeof value !== 'number' || !Number.isInteger(value)) {
+        throw new HostDispatcherError('HANDLER_ERROR', `${path} must be an integer`);
+    }
+    if (Object.is(value, -0)) {
+        throw new HostDispatcherError('HANDLER_ERROR', `${path} must not be -0`);
+    }
+    if (value < 0 || value > UINT32_MAX) {
+        throw new HostDispatcherError('HANDLER_ERROR', `${path} must be between 0 and ${UINT32_MAX}`);
+    }
+    if (value > max) {
+        if (allowOverflow) {
+            return null;
+        }
+        throw new HostDispatcherError('HANDLER_ERROR', `${path} exceeds max_units (${value} > ${max})`);
+    }
+    return value;
+}
+function fatal(code, message, cause) {
+    return {
+        kind: 'fatal',
+        error: new HostDispatcherError(code, message, { cause }),
+    };
+}
+function fatalLimitError(fn) {
+    return fatal('INVALID_ARGUMENTS', `fn_id=${fn.fn_id} request exceeded max_request_bytes (${fn.limits.max_request_bytes})`);
+}
+function asUint8Array(input) {
+    if (input instanceof Uint8Array) {
+        return input;
+    }
+    if (input instanceof ArrayBuffer) {
+        return new Uint8Array(input);
+    }
+    return new Uint8Array(input.buffer, input.byteOffset, input.byteLength);
+}
+function isSizeRelatedDvError(err) {
+    return (err instanceof DvError &&
+        (err.code === 'ENCODED_TOO_LARGE' ||
+            err.code === 'STRING_TOO_LONG' ||
+            err.code === 'ARRAY_TOO_LONG' ||
+            err.code === 'MAP_TOO_LONG' ||
+            err.code === 'DEPTH_EXCEEDED'));
+}
+function withErrorTags(fn) {
+    const errorTagMap = new Map();
+    for (const entry of fn.error_codes) {
+        errorTagMap.set(entry.code, entry.tag);
+    }
+    return { ...fn, errorTagMap };
+}
+function stringifyError(err) {
+    if (err instanceof Error) {
+        return err.message;
+    }
+    return String(err);
+}
+function withinBounds(view, offset, length) {
+    if (length === 0) {
+        return offset <= view.byteLength;
+    }
+    if (offset > view.byteLength) {
+        return false;
+    }
+    return length <= view.byteLength - offset;
+}
+function rangesOverlap(aOffset, aLength, bOffset, bLength) {
+    if (aLength === 0 || bLength === 0) {
+        return false;
+    }
+    return aOffset < bOffset + bLength && bOffset < aOffset + aLength;
+}

package/dist/lib/quickjs-runtime.d.ts

@@ -0,0 +1,35 @@
+import { DV, DvLimits } from '@blue-quickjs/dv';
+export interface ProgramArtifact {
+    code: string;
+    abiId: string;
+    abiVersion: number;
+    abiManifestHash: string;
+    engineBuildHash?: string;
+}
+export interface ProgramArtifactLimits {
+    maxCodeUnits: number;
+    maxAbiIdLength: number;
+}
+export declare const PROGRAM_LIMIT_DEFAULTS: Readonly<ProgramArtifactLimits>;
+export interface ProgramValidationOptions {
+    limits?: Partial<ProgramArtifactLimits>;
+}
+export interface InputEnvelope {
+    event: DV;
+    eventCanonical: DV;
+    steps: DV;
+}
+export interface InputValidationOptions {
+    dvLimits?: Partial<DvLimits>;
+}
+export type RuntimeValidationErrorCode = 'INVALID_TYPE' | 'MISSING_FIELD' | 'UNKNOWN_FIELD' | 'EMPTY_STRING' | 'EXCEEDS_LIMIT' | 'INVALID_HEX' | 'OUT_OF_RANGE' | 'DV_INVALID';
+export declare class RuntimeValidationError extends Error {
+    readonly code: RuntimeValidationErrorCode;
+    readonly path?: string | undefined;
+    constructor(code: RuntimeValidationErrorCode, message: string, path?: string | undefined, options?: {
+        cause?: unknown;
+    });
+}
+export declare function validateProgramArtifact(value: unknown, options?: ProgramValidationOptions): ProgramArtifact;
+export declare function validateInputEnvelope(value: unknown, options?: InputValidationOptions): InputEnvelope;
+//# sourceMappingURL=quickjs-runtime.d.ts.map

package/dist/lib/quickjs-runtime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"quickjs-runtime.d.ts","sourceRoot":"","sources":["../../src/lib/quickjs-runtime.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,EAAE,EAGF,QAAQ,EAET,MAAM,kBAAkB,CAAC;AAK1B,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,CAAC;IACnB,eAAe,EAAE,MAAM,CAAC;IACxB,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,qBAAqB;IACpC,YAAY,EAAE,MAAM,CAAC;IACrB,cAAc,EAAE,MAAM,CAAC;CACxB;AAED,eAAO,MAAM,sBAAsB,EAAE,QAAQ,CAAC,qBAAqB,CAGlE,CAAC;AAEF,MAAM,WAAW,wBAAwB;IACvC,MAAM,CAAC,EAAE,OAAO,CAAC,qBAAqB,CAAC,CAAC;CACzC;AAED,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,EAAE,CAAC;IACV,cAAc,EAAE,EAAE,CAAC;IACnB,KAAK,EAAE,EAAE,CAAC;CACX;AAED,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,EAAE,OAAO,CAAC,QAAQ,CAAC,CAAC;CAC9B;AAED,MAAM,MAAM,0BAA0B,GAClC,cAAc,GACd,eAAe,GACf,eAAe,GACf,cAAc,GACd,eAAe,GACf,aAAa,GACb,cAAc,GACd,YAAY,CAAC;AAEjB,qBAAa,sBAAuB,SAAQ,KAAK;aAE7B,IAAI,EAAE,0BAA0B;aAEhC,IAAI,CAAC,EAAE,MAAM;gBAFb,IAAI,EAAE,0BAA0B,EAChD,OAAO,EAAE,MAAM,EACC,IAAI,CAAC,EAAE,MAAM,YAAA,EAC7B,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE;CAKhC;AAED,wBAAgB,uBAAuB,CACrC,KAAK,EAAE,OAAO,EACd,OAAO,CAAC,EAAE,wBAAwB,GACjC,eAAe,CAyCjB;AAED,wBAAgB,qBAAqB,CACnC,KAAK,EAAE,OAAO,EACd,OAAO,CAAC,EAAE,sBAAsB,GAC/B,aAAa,CAkBf"}

package/dist/lib/quickjs-runtime.js

@@ -0,0 +1,143 @@
+import { DV_LIMIT_DEFAULTS, DvError, validateDv, } from '@blue-quickjs/dv';
+const UINT32_MAX = 0xffffffff;
+const SHA256_HEX_LENGTH = 64;
+const HEX_RE = /^[0-9a-f]+$/;
+export const PROGRAM_LIMIT_DEFAULTS = {
+    maxCodeUnits: 1_048_576, // 1 MiB in UTF-16 code units
+    maxAbiIdLength: 128,
+};
+export class RuntimeValidationError extends Error {
+    code;
+    path;
+    constructor(code, message, path, options) {
+        super(message, options);
+        this.code = code;
+        this.path = path;
+        this.name = 'RuntimeValidationError';
+    }
+}
+export function validateProgramArtifact(value, options) {
+    const limits = normalizeProgramLimits(options?.limits);
+    const program = expectPlainObject(value, 'program');
+    enforceExactKeys(program, ['code', 'abiId', 'abiVersion', 'abiManifestHash', 'engineBuildHash'], 'program');
+    const code = expectString(program.code, 'program.code', {
+        maxLength: limits.maxCodeUnits,
+        allowEmpty: true,
+    });
+    const abiId = expectString(program.abiId, 'program.abiId', {
+        maxLength: limits.maxAbiIdLength,
+    });
+    const abiVersion = expectUint(program.abiVersion, 1, UINT32_MAX, 'program.abiVersion');
+    const abiManifestHash = expectHexString(program.abiManifestHash, 'program.abiManifestHash', { exactLength: SHA256_HEX_LENGTH });
+    const engineBuildHash = program.engineBuildHash !== undefined
+        ? expectHexString(program.engineBuildHash, 'program.engineBuildHash', {
+            exactLength: SHA256_HEX_LENGTH,
+        })
+        : undefined;
+    return {
+        code,
+        abiId,
+        abiVersion,
+        abiManifestHash,
+        engineBuildHash,
+    };
+}
+export function validateInputEnvelope(value, options) {
+    const dvLimits = normalizeDvLimits(options?.dvLimits);
+    const input = expectPlainObject(value, 'input');
+    enforceExactKeys(input, ['event', 'eventCanonical', 'steps'], 'input');
+    const event = validateDvField(input.event, dvLimits, 'input.event');
+    const eventCanonical = validateDvField(input.eventCanonical, dvLimits, 'input.eventCanonical');
+    const steps = validateDvField(input.steps, dvLimits, 'input.steps');
+    return {
+        event,
+        eventCanonical,
+        steps,
+    };
+}
+function validateDvField(value, limits, path) {
+    try {
+        validateDv(value, { limits });
+        return value;
+    }
+    catch (err) {
+        if (err instanceof DvError) {
+            throw runtimeError('DV_INVALID', `${path} is not valid DV: ${err.message}`, path, err);
+        }
+        throw err;
+    }
+}
+function expectPlainObject(value, path) {
+    if (value === null ||
+        typeof value !== 'object' ||
+        Array.isArray(value) ||
+        Object.getPrototypeOf(value) !== Object.prototype) {
+        throw runtimeError('INVALID_TYPE', `${path} must be a plain object`, path);
+    }
+    return value;
+}
+function enforceExactKeys(value, allowed, path) {
+    for (const key of Object.keys(value)) {
+        if (!allowed.includes(key)) {
+            throw runtimeError('UNKNOWN_FIELD', `${path} contains unknown field "${key}"`, `${path}.${key}`);
+        }
+    }
+}
+function expectString(value, path, options) {
+    if (typeof value !== 'string') {
+        throw runtimeError('INVALID_TYPE', `${path} must be a string`, path);
+    }
+    if (!options?.allowEmpty && value.length === 0) {
+        throw runtimeError('EMPTY_STRING', `${path} must not be empty`, path);
+    }
+    if (options?.maxLength !== undefined && value.length > options.maxLength) {
+        throw runtimeError('EXCEEDS_LIMIT', `${path} exceeds maxLength (${value.length} > ${options.maxLength})`, path);
+    }
+    return value;
+}
+function expectHexString(value, path, options) {
+    const hex = expectString(value, path);
+    if (options.exactLength !== undefined && hex.length !== options.exactLength) {
+        throw runtimeError('INVALID_HEX', `${path} must be ${options.exactLength} hex characters`, path);
+    }
+    if (options.maxLength !== undefined && hex.length > options.maxLength) {
+        throw runtimeError('EXCEEDS_LIMIT', `${path} exceeds maxLength (${hex.length} > ${options.maxLength})`, path);
+    }
+    if (hex.length % 2 !== 0) {
+        throw runtimeError('INVALID_HEX', `${path} must have an even number of hex characters`, path);
+    }
+    if (!HEX_RE.test(hex)) {
+        throw runtimeError('INVALID_HEX', `${path} must be lowercase hex`, path);
+    }
+    return hex;
+}
+function expectUint(value, min, max, path) {
+    if (typeof value !== 'number' || !Number.isInteger(value)) {
+        throw runtimeError('INVALID_TYPE', `${path} must be an integer`, path);
+    }
+    if (Object.is(value, -0)) {
+        throw runtimeError('OUT_OF_RANGE', `${path} must not be -0`, path);
+    }
+    if (value < min || value > max) {
+        throw runtimeError('OUT_OF_RANGE', `${path} must be between ${min} and ${max}`, path);
+    }
+    return value;
+}
+function normalizeProgramLimits(overrides) {
+    return {
+        maxCodeUnits: overrides?.maxCodeUnits ?? PROGRAM_LIMIT_DEFAULTS.maxCodeUnits,
+        maxAbiIdLength: overrides?.maxAbiIdLength ?? PROGRAM_LIMIT_DEFAULTS.maxAbiIdLength,
+    };
+}
+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 runtimeError(code, message, path, cause) {
+    return new RuntimeValidationError(code, message, path, { cause });
+}

package/dist/lib/runtime.d.ts

@@ -0,0 +1,33 @@
+import { type AbiManifest, type CanonicalAbiManifest } from '@blue-quickjs/abi-manifest';
+import { type QuickjsWasmArtifact, type QuickjsWasmBuildMetadata, type QuickjsWasmBuildType, type QuickjsWasmVariant } from '@blue-quickjs/quickjs-wasm';
+import { type HostCallImport, type HostDispatcher, type HostDispatcherHandlers, type HostDispatcherOptions } from './host-dispatcher.js';
+export interface QuickjsWasmModule {
+    HEAPU8: Uint8Array;
+    cwrap<T extends (...args: unknown[]) => unknown>(ident: string, returnType: string | null, argTypes: Array<string | null>): T;
+    UTF8ToString(ptr: number, maxBytesToRead?: number): string;
+    _malloc(size: number): number;
+    _free(ptr: number): void;
+    ready?: Promise<unknown>;
+}
+export interface RuntimeArtifactSelection {
+    variant?: QuickjsWasmVariant;
+    buildType?: QuickjsWasmBuildType;
+    metadata?: QuickjsWasmBuildMetadata;
+    wasmBinary?: Uint8Array;
+}
+export interface CreateRuntimeOptions extends HostDispatcherOptions, RuntimeArtifactSelection {
+    manifest: AbiManifest;
+    handlers: HostDispatcherHandlers;
+}
+export interface RuntimeInstance {
+    module: QuickjsWasmModule;
+    dispatcher: HostDispatcher;
+    hostCall: HostCallImport;
+    manifest: CanonicalAbiManifest;
+    artifact: QuickjsWasmArtifact;
+    metadata: QuickjsWasmBuildMetadata;
+    variant: QuickjsWasmVariant;
+    buildType: QuickjsWasmBuildType;
+}
+export declare function createRuntime(options: CreateRuntimeOptions): Promise<RuntimeInstance>;
+//# sourceMappingURL=runtime.d.ts.map

package/dist/lib/runtime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime.d.ts","sourceRoot":"","sources":["../../src/lib/runtime.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,WAAW,EAChB,KAAK,oBAAoB,EAC1B,MAAM,4BAA4B,CAAC;AACpC,OAAO,EACL,KAAK,mBAAmB,EACxB,KAAK,wBAAwB,EAC7B,KAAK,oBAAoB,EACzB,KAAK,kBAAkB,EAIxB,MAAM,4BAA4B,CAAC;AACpC,OAAO,EAGL,KAAK,cAAc,EAEnB,KAAK,cAAc,EACnB,KAAK,sBAAsB,EAC3B,KAAK,qBAAqB,EAC3B,MAAM,sBAAsB,CAAC;AAM9B,MAAM,WAAW,iBAAiB;IAChC,MAAM,EAAE,UAAU,CAAC;IACnB,KAAK,CAAC,CAAC,SAAS,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,OAAO,EAC7C,KAAK,EAAE,MAAM,EACb,UAAU,EAAE,MAAM,GAAG,IAAI,EACzB,QAAQ,EAAE,KAAK,CAAC,MAAM,GAAG,IAAI,CAAC,GAC7B,CAAC,CAAC;IACL,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,cAAc,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAC3D,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC;IAC9B,KAAK,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IAEzB,KAAK,CAAC,EAAE,OAAO,CAAC,OAAO,CAAC,CAAC;CAC1B;AAED,MAAM,WAAW,wBAAwB;IACvC,OAAO,CAAC,EAAE,kBAAkB,CAAC;IAC7B,SAAS,CAAC,EAAE,oBAAoB,CAAC;IACjC,QAAQ,CAAC,EAAE,wBAAwB,CAAC;IACpC,UAAU,CAAC,EAAE,UAAU,CAAC;CACzB;AAED,MAAM,WAAW,oBACf,SAAQ,qBAAqB,EAAE,wBAAwB;IACvD,QAAQ,EAAE,WAAW,CAAC;IACtB,QAAQ,EAAE,sBAAsB,CAAC;CAClC;AAED,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,iBAAiB,CAAC;IAC1B,UAAU,EAAE,cAAc,CAAC;IAC3B,QAAQ,EAAE,cAAc,CAAC;IACzB,QAAQ,EAAE,oBAAoB,CAAC;IAC/B,QAAQ,EAAE,mBAAmB,CAAC;IAC9B,QAAQ,EAAE,wBAAwB,CAAC;IACnC,OAAO,EAAE,kBAAkB,CAAC;IAC5B,SAAS,EAAE,oBAAoB,CAAC;CACjC;AAQD,wBAAsB,aAAa,CACjC,OAAO,EAAE,oBAAoB,GAC5B,OAAO,CAAC,eAAe,CAAC,CA8D1B"}

package/dist/lib/runtime.js

@@ -0,0 +1,56 @@
+import { getQuickjsWasmArtifact, loadQuickjsWasmBinary, loadQuickjsWasmMetadata, } from '@blue-quickjs/quickjs-wasm';
+import { createHostCallImport, createHostDispatcher, } from './host-dispatcher.js';
+const UINT32_MAX = 0xffffffff;
+const DEFAULT_VARIANT = 'wasm32';
+const DEFAULT_BUILD_TYPE = 'release';
+export async function createRuntime(options) {
+    const variant = options.variant ?? DEFAULT_VARIANT;
+    const buildType = options.buildType ?? DEFAULT_BUILD_TYPE;
+    if (variant !== 'wasm32') {
+        throw new Error(`quickjs-runtime supports wasm32 only; host_call pointers are 32-bit (received variant=${variant})`);
+    }
+    const metadata = options.metadata ??
+        (await loadQuickjsWasmMetadata().catch((error) => {
+            throw new Error(`Failed to load QuickJS wasm metadata: ${String(error)}`);
+        }));
+    const artifact = await getQuickjsWasmArtifact(variant, buildType, metadata);
+    const wasmBinary = options.wasmBinary ??
+        (await loadQuickjsWasmBinary(variant, buildType, metadata));
+    const dispatcher = createHostDispatcher(options.manifest, options.handlers, options);
+    const hostMemory = { buffer: new ArrayBuffer(0) };
+    const hostCall = createHostCallImport(dispatcher, hostMemory);
+    const guardedHostCall = (...args) => {
+        if (hostMemory.buffer.byteLength === 0) {
+            return UINT32_MAX;
+        }
+        return hostCall(...args);
+    };
+    const moduleFactory = (await import(artifact.loaderUrl.href))
+        .default;
+    const module = await moduleFactory({
+        host: { host_call: guardedHostCall },
+        wasmBinary: toArrayBuffer(wasmBinary),
+        locateFile: (path) => path.endsWith('.wasm') ? artifact.wasmUrl.href : path,
+    });
+    const buffer = module?.HEAPU8?.buffer;
+    if (!buffer) {
+        throw new Error('QuickJS wasm module did not expose linear memory');
+    }
+    hostMemory.buffer = buffer;
+    return {
+        module,
+        dispatcher,
+        hostCall,
+        manifest: dispatcher.manifest,
+        artifact,
+        metadata,
+        variant,
+        buildType,
+    };
+}
+function toArrayBuffer(view) {
+    if (view.byteOffset === 0 && view.byteLength === view.buffer.byteLength) {
+        return view.buffer;
+    }
+    return view.slice().buffer;
+}