@hew-lang/sandbox-vm 0.9.3 → 0.10.0

package/dist/interpreter/v1/value-operations.js

@@ -1,4 +1,4 @@
-import { UNIT, cloneValue, compareUtf8, } from "../values.js";
+import { UNIT, mutableVector, vectorItems, vectorLength, vectorElement, cloneValue, compareUtf8, } from "../values.js";
 import { runtimeTag, } from "./package.js";
 import { ShimFault } from "./shims.js";
 import { actorIdentical } from "./actor-identity.js";
@@ -109,13 +109,13 @@ export function* selectedValue(pkg, id, args) {
     if (plan.ty === "bytes") {
         if (left.kind !== "vector")
             throw new Error("bytes capability has no bytes");
-        const bytes = left.items.map((value) => Number(bits(value, "u8")));
+        const bytes = vectorItems(left).map((value) => Number(bits(value, "u8")));
         if (hash)
             return integer(bytesHash(bytes));
         if (equality)
             return boolean(right?.kind === "vector" &&
-                bytes.length === right.items.length &&
-                bytes.every((value, i) => BigInt(value) === bits(right.items[i], "u8")));
+                bytes.length === vectorLength(right) &&
+                bytes.every((value, i) => BigInt(value) === bits(vectorElement(right, i), "u8")));
         throw new Error("bytes ordering is outside the checked capability domain");
     }
     if (left.kind === "actor" || left.kind === "supervisor") {
@@ -151,7 +151,7 @@ export function* selectedValue(pkg, id, args) {
         selections = plan.variants?.[left.tag] ?? [];
     }
     else if (left.kind === "vector") {
-        fields = left.items;
+        fields = vectorItems(left);
         if (hash) {
             const elementSelection = components[0];
             if (!elementSelection)
@@ -160,9 +160,10 @@ export function* selectedValue(pkg, id, args) {
             vectorHashLength = fields.length;
         }
         else {
-            if (right?.kind !== "vector" || left.items.length !== right.items.length)
+            if (right?.kind !== "vector" ||
+                vectorLength(left) !== vectorLength(right))
                 return boolean(false);
-            others = right.items;
+            others = vectorItems(right);
             selections = fields.map(() => components[0]);
         }
     }
@@ -324,17 +325,20 @@ export function* sharedOperation(operation, args, owner, typeName, option) {
 /** Open-addressed collection operations preserve native callback ordering:
  * growth hashes occupied slots before probing the incoming key. Staged slots
  * borrow their owners until every fallible callback has completed. */
-export function* collectionOperation(pkg, request, args, callbacks, shape) {
+export function* collectionOperation(pkg, request, args, callbacks, shape, elementType) {
     const { family, operation } = request;
     if (family === "Vector") {
         const receiver = args[0];
         if (receiver?.kind !== "vector")
             throw new Error("vector operation has no vector");
         if (operation === "Clear") {
+            mutableVector(receiver);
             const items = receiver.items.splice(0);
             yield {
                 kind: "release",
                 value: { kind: "vector", elementType: receiver.elementType, items },
+                retained: items,
+                retainedType: elementType,
             };
             return receiver;
         }
@@ -343,14 +347,15 @@ export function* collectionOperation(pkg, request, args, callbacks, shape) {
             if (index?.kind !== "i64")
                 throw new Error("vector mutation has no index");
             const at = Number(index.value);
-            if (at < 0 || at >= receiver.items.length)
-                throw new ShimFault("vector_bounds", "vector index out of bounds");
+            if (at < 0 || at >= vectorLength(receiver))
+                throw new ShimFault("vector_bounds", `vector index ${at} out of bounds for length ${vectorLength(receiver)}`);
+            mutableVector(receiver);
             const old = receiver.items[at];
             receiver.items[at] = args[2];
-            yield { kind: "release", value: old };
+            yield { kind: "release", value: old, retainedType: elementType };
             return receiver;
         }
-        for (const item of receiver.items) {
+        for (const item of vectorItems(receiver)) {
             const equal = yield* selectedValue(pkg, callbacks[0], [item, args[1]]);
             if (equal.kind !== "bool")
                 throw new Error("Eq returned a non-boolean value");
@@ -377,6 +382,7 @@ export function* collectionOperation(pkg, request, args, callbacks, shape) {
         receiver.tombstones = new Set();
         yield {
             kind: "release",
+            retained: entries.flatMap((entry) => [entry.key, entry.value]),
             value: {
                 kind: "vector",
                 elementType: "",
@@ -389,15 +395,22 @@ export function* collectionOperation(pkg, request, args, callbacks, shape) {
         operation === "Values" ||
         operation === "Elements" ||
         operation === "Entries") {
-        return {
+        const result = {
             kind: "vector",
             elementType: "",
-            items: [...receiver.entries.values()].map(({ key, value }) => operation === "Values"
-                ? cloneValue(value)
-                : operation === "Entries"
-                    ? tuple(cloneValue(key), cloneValue(value))
-                    : cloneValue(key)),
+            items: [],
         };
+        const items = [...receiver.entries.values()].map(({ key, value }) => operation === "Values"
+            ? cloneValue(value)
+            : operation === "Entries"
+                ? tuple(cloneValue(key), cloneValue(value))
+                : cloneValue(key));
+        // Native snapshots push into an initially empty Vec, retaining its normal
+        // growth capacity. A later semantic clone may use exact live length.
+        mutableVector(result, items.length);
+        for (const item of items)
+            result.items.push(item);
+        return result;
     }
     let staged = receiver;
     if (operation === "Insert" &&
@@ -435,6 +448,7 @@ export function* collectionOperation(pkg, request, args, callbacks, shape) {
         return cloneValue(entry.value);
     }
     if (operation === "Insert") {
+        receiver.prepareInsert?.(staged, result.slot, entry?.key ?? args[1], family === "Set" ? UNIT : args[2], family !== "Set" && !entry);
         receiver.entries = staged.entries;
         receiver.capacity = staged.capacity;
         receiver.tombstones = staged.tombstones;

package/dist/interpreter/values.d.ts

@@ -1,6 +1,5 @@
 import type { JsonValue } from "./types.js";
 import { IndexedString } from "./strings.js";
-import type { EncodingNode, EncodingFormat } from "./v1/encoding-values.js";
 export { stringValue } from "./strings.js";
 /** One creator-owned membership list; payload destruction uses the ordinary VM release path. */
 export interface RcOwner {
@@ -8,6 +7,8 @@ export interface RcOwner {
     closed: boolean;
 }
 export interface RcCell {
+    managedLease?: import("./v1/managed-budget.js").ManagedLease;
+    managedPayload?: number;
     value: VmValue;
     refs: number;
     weak: number;
@@ -15,11 +16,27 @@ export interface RcCell {
     owner: RcOwner | null;
     typeName: string;
 }
-export type VmValue = import("./v1/semaphores.js").SemaphoreHandle | {
-    kind: "encoding";
-    format: EncodingFormat;
-    value: EncodingNode | null;
-} | {
+/** The language payload allocation. JS arrays holding view metadata do not
+ * determine its capacity or identity. Bytes views retain this complete owner. */
+export interface VectorStorage {
+    items: VmValue[];
+    capacity: number;
+    owners: number;
+    bytes: boolean;
+    shareOnCopy: boolean;
+}
+export interface VmVector {
+    kind: "vector";
+    elementType: string;
+    items: VmValue[];
+    storage?: VectorStorage;
+    offset?: number;
+    /** Normal Vec live length; absent for materialized vectors and byte views. */
+    length?: number;
+    closed?: boolean;
+    prepareMutation?: (capacity: number, detached: boolean, appended?: readonly VmValue[]) => void;
+}
+export type VmValue = import("./v1/semaphores.js").SemaphoreHandle | import("./v1/encoding-storage.js").EncodingOwner | {
     kind: "rc";
     cell: RcCell | null;
     closed: boolean;
@@ -86,17 +103,14 @@ export type VmValue = import("./v1/semaphores.js").SemaphoreHandle | {
     typeId: string;
     shape?: number;
     fields: VmValue[];
+    managedCaptures?: readonly number[];
 } | {
     kind: "enum";
     typeId: string;
     shape: number;
     tag: number;
     payload: VmValue[];
-} | {
-    kind: "vector";
-    elementType: string;
-    items: VmValue[];
-}
+} | VmVector
 /** A map or set owns its occupied slots. Selected Hash/Eq operations probe
  *  the table; tombstones preserve collision chains across removal. */
  | {
@@ -107,6 +121,9 @@ export type VmValue = import("./v1/semaphores.js").SemaphoreHandle | {
     }>;
     capacity?: number;
     tombstones?: Set<number>;
+    prepareInsert?: (staged: Extract<VmValue, {
+        kind: "map";
+    }>, slot: string, key: VmValue, value: VmValue, copyKey: boolean) => void;
 }
 /** A trait object: the vtable the checker selected, and the value it wraps.
  *  A `dyn.call` resolves its method through `vtable`, never through the
@@ -115,6 +132,7 @@ export type VmValue = import("./v1/semaphores.js").SemaphoreHandle | {
     kind: "dyn";
     vtable: number;
     value: VmValue;
+    managedPayload?: number;
 }
 /** A first-class function reference materialised by `const.function`.
  *  `id` is the bytecode function id (e.g. `"fn:my_handler"`).
@@ -135,10 +153,26 @@ export type VmValue = import("./v1/semaphores.js").SemaphoreHandle | {
     }>;
     specialization: number | null;
     environment: VmValue;
+    managedCaptures?: readonly number[];
 };
 export declare const UNIT: VmValue;
 export declare function compareUtf8(a: string, b: string): number;
 export declare function cloneValue(value: VmValue): VmValue;
+/** The live range is header metadata; the backing keeps its full capacity. */
+export declare function vectorLength(value: VmVector): number;
+export declare function vectorElement(value: VmVector, index: number): VmValue | undefined;
+/** Materialize a view only for operations that already traverse its elements. */
+export declare function vectorItems(value: VmVector): VmValue[];
+export declare function vectorStorage(value: VmVector): VectorStorage;
+export declare function byteVectorValue(items: VmValue[]): VmVector;
+export declare function sliceByteVector(value: VmVector, start: number, end: number): VmVector;
+/** Establish uniqueness before any mutation, preserving native capacity rules. */
+export declare function mutableVector(value: VmVector, needed?: number, appended?: readonly VmValue[]): VmVector;
+/** Move a normal Vec end in constant time, retaining its allocation identity. */
+export declare function takeVectorEnd(value: VmVector, back: boolean): VmValue;
+/** Consume one handle; only its remaining live elements need destruction. */
+export declare function releaseVector(value: VmVector): VmValue[];
+export declare function clearByteVector(value: VmVector): VmVector;
 export declare function valueFromLiteral(value: JsonValue): VmValue;
 export declare function renderF64(value: number): string;
 export declare function renderStdout(value: VmValue): string;

package/dist/interpreter/values.js

@@ -1,4 +1,5 @@
 import { stringValue } from "./strings.js";
+import { cloneEncoding } from "./v1/encoding-storage.js";
 export { stringValue } from "./strings.js";
 export const UNIT = { kind: "unit" };
 const UTF8_ENCODER = new TextEncoder();
@@ -18,7 +19,7 @@ const I64_LITERAL_DECIMAL = /^(?:0|-?[1-9]\d*)$/;
 export function cloneValue(value) {
     switch (value.kind) {
         case "encoding":
-            return { ...value, value: structuredClone(value.value) };
+            return cloneEncoding(value);
         case "rc":
             if (value.closed)
                 throw new Error("cannot copy a released Rc");
@@ -69,6 +70,7 @@ export function cloneValue(value) {
                 kind: "record",
                 typeId: value.typeId,
                 shape: value.shape,
+                managedCaptures: value.managedCaptures,
                 fields: value.fields.map(cloneValue),
             };
         case "enum":
@@ -80,16 +82,13 @@ export function cloneValue(value) {
                 payload: value.payload.map(cloneValue),
             };
         case "vector":
-            return {
-                kind: "vector",
-                elementType: value.elementType,
-                items: value.items.map(cloneValue),
-            };
+            return cloneVector(value);
         case "dyn":
             return {
                 kind: "dyn",
                 vtable: value.vtable,
                 value: cloneValue(value.value),
+                managedPayload: value.managedPayload,
             };
         case "closure":
             return {
@@ -97,6 +96,7 @@ export function cloneValue(value) {
                 entries: value.entries,
                 specialization: value.specialization,
                 environment: cloneValue(value.environment),
+                managedCaptures: value.managedCaptures,
             };
         case "map":
             return {
@@ -110,6 +110,174 @@ export function cloneValue(value) {
             };
     }
 }
+/** The live range is header metadata; the backing keeps its full capacity. */
+export function vectorLength(value) {
+    return value.length ?? value.items.length;
+}
+export function vectorElement(value, index) {
+    if (index < 0 || index >= vectorLength(value))
+        return undefined;
+    return value.items[(value.length === undefined ? 0 : (value.offset ?? 0)) + index];
+}
+/** Materialize a view only for operations that already traverse its elements. */
+export function vectorItems(value) {
+    return value.length === undefined
+        ? value.items
+        : value.items.slice(value.offset ?? 0, (value.offset ?? 0) + value.length);
+}
+export function vectorStorage(value) {
+    if (value.closed)
+        throw new Error("cannot read a released vector");
+    return (value.storage ??= {
+        items: value.items,
+        capacity: value.items.length,
+        owners: 1,
+        bytes: false,
+        shareOnCopy: false,
+    });
+}
+export function byteVectorValue(items) {
+    return {
+        kind: "vector",
+        elementType: "u8",
+        items,
+        storage: {
+            items,
+            capacity: items.length ? Math.max(items.length, 16) : 0,
+            owners: 1,
+            bytes: true,
+            shareOnCopy: true,
+        },
+        offset: 0,
+    };
+}
+function cloneVector(value) {
+    const storage = vectorStorage(value);
+    // Native Vec clones discard an empty receiver's spare capacity. Bytes
+    // clones retain their allocation even when the visible length is zero.
+    if (storage.bytes || (storage.shareOnCopy && vectorLength(value) !== 0)) {
+        storage.owners++;
+        return { ...value, storage, closed: false };
+    }
+    const items = vectorItems(value).map(cloneValue);
+    return {
+        kind: "vector",
+        elementType: value.elementType,
+        items,
+        storage: { ...storage, items, capacity: items.length, owners: 1 },
+    };
+}
+export function sliceByteVector(value, start, end) {
+    const storage = vectorStorage(value);
+    if (!storage.bytes)
+        throw new Error("bytes slice has no bytes storage");
+    if (start === end)
+        return byteVectorValue([]);
+    storage.owners++;
+    return {
+        kind: "vector",
+        elementType: value.elementType,
+        items: value.items.slice(start, end),
+        storage,
+        offset: (value.offset ?? 0) + start,
+    };
+}
+/** Establish uniqueness before any mutation, preserving native capacity rules. */
+export function mutableVector(value, needed = vectorLength(value), appended) {
+    let storage = vectorStorage(value);
+    let capacity = storage.capacity;
+    const detached = storage.owners !== 1;
+    if (detached && storage.bytes)
+        capacity = Math.max(vectorLength(value), 16);
+    if (needed > capacity) {
+        if (storage.bytes)
+            capacity = Math.max(Math.min(capacity * 2, 0xffffffff), needed, 16);
+        else {
+            capacity = capacity || 4;
+            while (capacity < needed)
+                capacity *= 2;
+        }
+    }
+    if (!Number.isSafeInteger(capacity) ||
+        (storage.bytes && capacity > 0xffffffff))
+        throw new Error("vector capacity overflow");
+    if (detached || capacity !== storage.capacity || appended?.length)
+        value.prepareMutation?.(capacity, detached, appended);
+    if (detached) {
+        const items = vectorItems(value).map(cloneValue);
+        storage.owners--;
+        storage = { ...storage, items, capacity, owners: 1 };
+        value.storage = storage;
+        value.items = items;
+        value.offset = 0;
+        value.length = undefined;
+    }
+    else if (!storage.bytes && value.length !== undefined) {
+        // A sole remaining view can reclaim its consumed prefix without
+        // changing the language allocation's identity or retained capacity.
+        if ((value.offset ?? 0) === 0)
+            value.items.length = value.length;
+        else
+            value.items = vectorItems(value);
+        storage.items = value.items;
+        value.offset = 0;
+        value.length = undefined;
+    }
+    if (capacity !== storage.capacity) {
+        storage.capacity = capacity;
+        value.offset = 0;
+    }
+    else if (storage.bytes && (value.offset ?? 0) + needed > capacity) {
+        value.offset = 0;
+    }
+    return value;
+}
+/** Move a normal Vec end in constant time, retaining its allocation identity. */
+export function takeVectorEnd(value, back) {
+    const storage = vectorStorage(value);
+    const length = vectorLength(value);
+    if (length === 0)
+        throw new Error("cannot take an empty vector end");
+    if (storage.bytes) {
+        mutableVector(value);
+        return (back ? value.items.pop() : value.items.shift());
+    }
+    const start = value.offset ?? 0;
+    const index = start + (back ? length - 1 : 0);
+    const item = value.items[index];
+    // Managed/affine storage is unique. Clear its moved slot immediately so
+    // the backing cannot retain payload references after ownership transfers.
+    // Shared callback-free plain bytes remain readable by other headers.
+    if (storage.owners === 1)
+        value.items[index] = UNIT;
+    else if (!storage.shareOnCopy)
+        throw new Error("managed vector unexpectedly shares its backing");
+    value.offset = start + (back ? 0 : 1);
+    value.length = length - 1;
+    return item;
+}
+/** Consume one handle; only its remaining live elements need destruction. */
+export function releaseVector(value) {
+    if (value.closed)
+        return [];
+    const storage = vectorStorage(value);
+    const items = --storage.owners === 0
+        ? storage.bytes
+            ? storage.items
+            : vectorItems(value)
+        : [];
+    value.closed = true;
+    return items;
+}
+export function clearByteVector(value) {
+    const storage = vectorStorage(value);
+    storage.owners--;
+    const empty = byteVectorValue([]);
+    value.items = empty.items;
+    value.storage = empty.storage;
+    value.offset = 0;
+    return value;
+}
 export function valueFromLiteral(value) {
     const taggedI64 = taggedI64Literal(value);
     if (taggedI64 !== null) {
@@ -258,7 +426,7 @@ export function renderStdout(value) {
                 payload: value.payload.map((field) => toJsonValue(field)),
             });
         case "vector":
-            return canonicalJson(value.items.map((item) => toJsonValue(item)));
+            return canonicalJson(vectorItems(value).map((item) => toJsonValue(item)));
         case "rc":
             return "Rc";
         case "weak":
@@ -316,7 +484,7 @@ export function toJsonValue(value) {
                 payload: value.payload.map(toJsonValue),
             };
         case "vector":
-            return value.items.map(toJsonValue);
+            return vectorItems(value).map(toJsonValue);
         case "rc":
             return "Rc";
         case "weak":

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "@hew-lang/sandbox-vm",
-  "version": "0.9.3",
+  "version": "0.10.0",
   "hewSource": {
-    "commit": "6e4bcf6b089c260bedae59320c68dab2137f5754",
-    "tag": "v0.9.3",
+    "commit": "75e14a2775f9af8fd77a6a907da277b2de666824",
+    "tag": "v0.10.0",
     "dirty": false
   },
   "description": "Deterministic TypeScript interpreter for the Hew educational sandbox",
@@ -21,7 +21,7 @@
     "cli/"
   ],
   "dependencies": {
-    "@hew-lang/wasm": "0.9.3"
+    "@hew-lang/wasm": "0.10.0"
   },
   "keywords": [
     "hew",