@hew-lang/sandbox-vm 0.6.1 → 0.6.2

package/README.md

@@ -48,6 +48,11 @@ The [package contract](bytecode/package-v1.md) describes the SIR projection.
 Source fixtures are compiled by the public compiler and executed to record
 deterministic traces. Tests also compare executable sources with native Hew.
 
+`RunOptions.argv` supplies process arguments, including the executable name at
+index zero. It defaults to `["main.hew"]` and is copied for each run. For example,
+`runBytecode(bytecode, { argv: ["greet", "--", "Zoë", ""] })` supplies those exact
+strings to `std.os.args()`. The VM never reads Node or browser process arguments.
+
 Typed serialization executes the shared Rust codecs in `@hew-lang/wasm`.
 Pass its initialized `executeCodec` export as `runBytecode`'s `codecBridge`
 option. The Node test host loads that package automatically; in a source

package/dist/interpreter/strings.d.ts

@@ -0,0 +1,21 @@
+export declare class IndexedString {
+    readonly kind = "string";
+    private storage;
+    private constructor();
+    static fromText(text: string): IndexedString;
+    private live;
+    get value(): string;
+    get scalarLength(): number;
+    get byteLength(): number;
+    encoded(): Uint8Array;
+    clone(): IndexedString;
+    release(): void;
+    scalarOffset(index: number): number | undefined;
+    at(index: number): string | undefined;
+    slice(start: number, end: number): IndexedString | undefined;
+    private scalarIndex;
+    find(needle: IndexedString, start?: number): number | undefined;
+    /** Consume this receiver, retaining the suffix's borrowed snapshot. */
+    append(suffix: IndexedString): IndexedString;
+}
+export declare function stringValue(value: string): IndexedString;

package/dist/interpreter/strings.js

@@ -0,0 +1,191 @@
+/** The VM's owned UTF-8 string storage. Scalar positions use the same
+ * bounded-stride index as native strings; no prefix is rescanned on access. */
+const INDEX_STRIDE = 32;
+const ENCODER = new TextEncoder();
+const DECODER = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true });
+function scalarWidth(first) {
+    return first < 0x80 ? 1 : first < 0xe0 ? 2 : first < 0xf0 ? 3 : 4;
+}
+function indexStorage(storage, byte, scalar) {
+    const offsets = storage.offsets;
+    while (byte < storage.byteLength) {
+        if (scalar % INDEX_STRIDE === 0)
+            offsets[scalar / INDEX_STRIDE] = byte;
+        byte += scalarWidth(storage.bytes[byte]);
+        scalar++;
+    }
+}
+function newStorage(bytes, capacity = bytes.length) {
+    const buffer = new Uint8Array(capacity);
+    buffer.set(bytes);
+    let scalars = 0;
+    for (let at = 0; at < bytes.length; at += scalarWidth(bytes[at]))
+        scalars++;
+    const storage = {
+        bytes: buffer,
+        byteLength: bytes.length,
+        scalarLength: scalars,
+        offsets: scalars === bytes.length ? null : [],
+        owners: 1,
+    };
+    if (storage.offsets)
+        indexStorage(storage, 0, 0);
+    return storage;
+}
+export class IndexedString {
+    kind = "string";
+    storage;
+    constructor(storage) {
+        this.storage = storage;
+    }
+    static fromText(text) {
+        return new IndexedString(newStorage(ENCODER.encode(text)));
+    }
+    live() {
+        if (!this.storage)
+            throw new Error("cannot read a released string");
+        return this.storage;
+    }
+    get value() {
+        return DECODER.decode(this.encoded());
+    }
+    get scalarLength() {
+        return this.live().scalarLength;
+    }
+    get byteLength() {
+        return this.live().byteLength;
+    }
+    encoded() {
+        const storage = this.live();
+        return storage.bytes.subarray(0, storage.byteLength);
+    }
+    clone() {
+        const storage = this.live();
+        storage.owners++;
+        return new IndexedString(storage);
+    }
+    release() {
+        if (this.storage) {
+            this.storage.owners--;
+            this.storage = null;
+        }
+    }
+    scalarOffset(index) {
+        const storage = this.live();
+        if (!Number.isSafeInteger(index) ||
+            index < 0 ||
+            index > storage.scalarLength)
+            return undefined;
+        if (index === storage.scalarLength)
+            return storage.byteLength;
+        if (!storage.offsets)
+            return index;
+        let byte = storage.offsets[Math.floor(index / INDEX_STRIDE)];
+        for (let tail = index % INDEX_STRIDE; tail > 0; tail--)
+            byte += scalarWidth(storage.bytes[byte]);
+        return byte;
+    }
+    at(index) {
+        if (index === this.scalarLength)
+            return undefined;
+        const byte = this.scalarOffset(index);
+        if (byte === undefined)
+            return undefined;
+        const storage = this.live();
+        return DECODER.decode(storage.bytes.subarray(byte, byte + scalarWidth(storage.bytes[byte])));
+    }
+    slice(start, end) {
+        const from = this.scalarOffset(start);
+        const to = this.scalarOffset(end);
+        if (from === undefined || to === undefined || from > to)
+            return undefined;
+        return new IndexedString(newStorage(this.live().bytes.subarray(from, to)));
+    }
+    scalarIndex(byte) {
+        const storage = this.live();
+        if (!storage.offsets)
+            return byte;
+        if (byte === storage.byteLength)
+            return storage.scalarLength;
+        let low = 0;
+        let high = storage.offsets.length;
+        while (low + 1 < high) {
+            const mid = Math.floor((low + high) / 2);
+            if (storage.offsets[mid] <= byte)
+                low = mid;
+            else
+                high = mid;
+        }
+        let scalar = low * INDEX_STRIDE;
+        for (let at = storage.offsets[low]; at < byte; at += scalarWidth(storage.bytes[at]))
+            scalar++;
+        return scalar;
+    }
+    find(needle, start = 0) {
+        const from = this.scalarOffset(start);
+        if (from === undefined)
+            return undefined;
+        const bytes = this.encoded();
+        const pattern = needle.encoded();
+        if (pattern.length === 0)
+            return start;
+        // KMP searches only the suffix requested by the caller. Decoding the
+        // complete value for String.indexOf would rescan its prefix on every call.
+        const prefixes = new Array(pattern.length).fill(0);
+        for (let i = 1, matched = 0; i < pattern.length; i++) {
+            while (matched && pattern[i] !== pattern[matched])
+                matched = prefixes[matched - 1];
+            if (pattern[i] === pattern[matched])
+                matched++;
+            prefixes[i] = matched;
+        }
+        for (let i = from, matched = 0; i < bytes.length; i++) {
+            while (matched && bytes[i] !== pattern[matched])
+                matched = prefixes[matched - 1];
+            if (bytes[i] === pattern[matched])
+                matched++;
+            if (matched === pattern.length)
+                return this.scalarIndex(i + 1 - matched);
+        }
+        return undefined;
+    }
+    /** Consume this receiver, retaining the suffix's borrowed snapshot. */
+    append(suffix) {
+        const bytes = suffix.encoded();
+        const added = suffix.scalarLength;
+        if (!bytes.length)
+            return this;
+        let storage = this.live();
+        const oldLength = storage.byteLength;
+        const oldScalars = storage.scalarLength;
+        const newLength = oldLength + bytes.length;
+        const capacity = newLength > storage.bytes.length
+            ? Math.max(newLength, storage.bytes.length * 2, 16)
+            : storage.bytes.length;
+        if (storage.owners !== 1) {
+            storage.owners--;
+            storage = newStorage(this.encoded(), capacity);
+            this.storage = storage;
+        }
+        else if (capacity !== storage.bytes.length) {
+            const buffer = new Uint8Array(capacity);
+            buffer.set(storage.bytes.subarray(0, oldLength));
+            storage.bytes = buffer;
+        }
+        storage.bytes.set(bytes, oldLength);
+        storage.byteLength = newLength;
+        storage.scalarLength += added;
+        if (storage.scalarLength !== newLength) {
+            if (storage.offsets)
+                indexStorage(storage, oldLength, oldScalars);
+            else {
+                storage.offsets = [];
+                indexStorage(storage, 0, 0);
+            }
+        }
+        return this;
+    }
+}
+export function stringValue(value) {
+    return IndexedString.fromText(value);
+}

package/dist/interpreter/types.d.ts

@@ -117,6 +117,8 @@ export interface SandboxTrace {
     };
 }
 export interface RunOptions {
+    /** Supplied process arguments including argv[0]. Defaults to ["main.hew"]. */
+    argv?: readonly string[];
     codecBridge?: (request: string) => string;
     propertyInput?: number[];
     fixtureId?: string;

package/dist/interpreter/unicode-data.d.ts

@@ -0,0 +1,4 @@
+export declare const CATEGORY_RANGES: readonly number[];
+export declare const UPPER_MAPPING: readonly number[];
+export declare const LOWER_MAPPING: readonly number[];
+export declare const TITLE_MAPPING: readonly number[];