@hew-lang/sandbox-vm 0.7.1 → 0.9.1

package/dist/interpreter/v1/semaphores.d.ts

@@ -0,0 +1,39 @@
+import type { VmValue } from "../values.js";
+interface State {
+    count: bigint;
+    waiting: Set<Acquisition>;
+}
+export interface SemaphoreHandle {
+    kind: "semaphore";
+    state: State;
+    closed: boolean;
+}
+type After = (nanos: bigint, ready: () => void) => () => void;
+/** A released permit belongs to its selected waiter until the resume edge
+ *  takes it. Cancellation before that edge hands the permit onwards. */
+export declare class Acquisition {
+    private readonly state;
+    private readonly ready;
+    private status;
+    private cancelTimer;
+    constructor(state: State, ready: (acquired: boolean) => void);
+    start(timeoutMs: bigint | null, after: After): void;
+    reserve(): void;
+    take(): void;
+    cancel(): void;
+    private detach;
+}
+/** The VM executes the compiler's semaphore operations against one shared
+ *  permit count. Explicit clones own independent handles, not independent counts. */
+export declare class Semaphores {
+    private readonly after;
+    constructor(after: After);
+    create(count: bigint): VmValue;
+    clone(value: VmValue): VmValue;
+    close(value: VmValue): void;
+    count(value: VmValue): bigint;
+    tryAcquire(value: VmValue): boolean;
+    release(value: VmValue): void;
+    acquire(value: VmValue, timeoutMs: bigint | null, ready: (acquired: boolean) => void): Acquisition;
+}
+export {};

package/dist/interpreter/v1/semaphores.js

@@ -0,0 +1,109 @@
+function handle(value) {
+    if (value.kind !== "semaphore" || value.closed)
+        throw new Error("expected a live semaphore handle");
+    return value;
+}
+function release(state) {
+    const waiter = state.waiting.values().next().value;
+    if (waiter)
+        waiter.reserve();
+    else if (state.count < 2147483647n)
+        state.count += 1n;
+}
+/** A released permit belongs to its selected waiter until the resume edge
+ *  takes it. Cancellation before that edge hands the permit onwards. */
+export class Acquisition {
+    state;
+    ready;
+    status = "waiting";
+    cancelTimer = () => { };
+    constructor(state, ready) {
+        this.state = state;
+        this.ready = ready;
+    }
+    start(timeoutMs, after) {
+        if (this.state.count > 0n) {
+            this.state.count -= 1n;
+            this.reserve();
+        }
+        else if (timeoutMs !== null && timeoutMs <= 0n) {
+            this.status = "finished";
+            this.ready(false);
+        }
+        else {
+            this.state.waiting.add(this);
+            if (timeoutMs !== null)
+                this.cancelTimer = after(timeoutMs * 1000000n, () => {
+                    if (this.status !== "waiting")
+                        return;
+                    this.detach();
+                    this.status = "finished";
+                    this.ready(false);
+                });
+        }
+    }
+    reserve() {
+        this.detach();
+        this.status = "reserved";
+        this.ready(true);
+    }
+    take() {
+        if (this.status === "reserved")
+            this.status = "finished";
+    }
+    cancel() {
+        this.detach();
+        const reserved = this.status === "reserved";
+        this.status = "finished";
+        if (reserved)
+            release(this.state);
+    }
+    detach() {
+        this.state.waiting.delete(this);
+        this.cancelTimer();
+        this.cancelTimer = () => { };
+    }
+}
+/** The VM executes the compiler's semaphore operations against one shared
+ *  permit count. Explicit clones own independent handles, not independent counts. */
+export class Semaphores {
+    after;
+    constructor(after) {
+        this.after = after;
+    }
+    create(count) {
+        if (count < 0n || count > 2147483647n)
+            throw new Error("semaphore capacity is outside the supported range");
+        return {
+            kind: "semaphore",
+            state: { count, waiting: new Set() },
+            closed: false,
+        };
+    }
+    clone(value) {
+        return { ...handle(value), closed: false };
+    }
+    close(value) {
+        if (value.kind !== "semaphore")
+            throw new Error("expected a semaphore handle");
+        value.closed = true;
+    }
+    count(value) {
+        return handle(value).state.count;
+    }
+    tryAcquire(value) {
+        const state = handle(value).state;
+        if (state.count === 0n)
+            return false;
+        state.count -= 1n;
+        return true;
+    }
+    release(value) {
+        release(handle(value).state);
+    }
+    acquire(value, timeoutMs, ready) {
+        const operation = new Acquisition(handle(value).state, ready);
+        operation.start(timeoutMs, this.after);
+        return operation;
+    }
+}

package/dist/interpreter/v1/shims.d.ts

@@ -11,11 +11,14 @@ export declare class ShimFault extends Error {
 export interface ShimHost {
     readonly argv: readonly string[];
     unixTimeMillis(): number;
+    monotonicTimeNanos(): bigint;
     fileError(operation: "HasError" | "LastErrorKind" | "LastErrno" | "LastError"): VmValue;
+    setFileError(message: string | null): void;
     calendarBridge?: (request: string) => string;
     codecBridge?: (request: string) => string;
     encodingError?(format: EncodingFormat, message?: string): string;
     pipes?: Pipes;
+    semaphores?: import("./semaphores.js").Semaphores;
     newPipe?(capacity: number): VmValue;
     generatorStream?(generator: VmValue): VmValue;
     encoderSink?(sink: VmValue, encoder: VmValue): VmValue;
@@ -47,7 +50,7 @@ type Ordinary = {
     bridge?: BridgeRequirement;
 };
 export type RuntimeContinuation = {
-    handler: "actor_caller" | "actor_refusal_log" | "structural_format" | "utf8_decode" | "close";
+    handler: "actor_caller" | "context_actor_id" | "context_supervisor" | "context_trace_span" | "actor_refusal_log" | "structural_format" | "utf8_decode" | "close";
 } | {
     handler: "supervisor_pool";
     operation: Extract<RuntimeFamilyEntry, {
@@ -209,6 +212,21 @@ export declare function resolveSuspension(term: SuspendTerm): Refused | {
         resumes: Array<import("./instructions.generated.js").Edge>;
         cancel: import("./instructions.generated.js").Edge | null;
         unwind: import("./instructions.generated.js").Edge | null;
+    } & {
+        kind: "SemaphoreAcquire";
+        detail: import("./instructions.generated.js").SemaphoreAcquireDetail;
+    }) | ({
+        span?: import("./instructions.generated.js").SpanV1 | null | null;
+    } & {
+        op: "suspend";
+        request_shapes?: import("./instructions.generated.js").RequestShapes | null | null;
+        result_shape?: number | null | null;
+        error_shape?: number | null | null;
+        inputs: Array<import("./instructions.generated.js").BoundaryOperand>;
+        result: import("./instructions.generated.js").CallResult;
+        resumes: Array<import("./instructions.generated.js").Edge>;
+        cancel: import("./instructions.generated.js").Edge | null;
+        unwind: import("./instructions.generated.js").Edge | null;
     } & {
         kind: "Ask";
         detail: import("./instructions.generated.js").AskDetail;

package/dist/interpreter/v1/shims.js

@@ -16,6 +16,22 @@ export class ShimFault extends Error {
         this.name = "ShimFault";
     }
 }
+function checkedWrite(host, value, stderr) {
+    try {
+        if (value.length !== 0) {
+            if (stderr)
+                host.writeStderr(value);
+            else
+                host.writeStdout(value);
+        }
+        host.setFileError(null);
+        return int(0n);
+    }
+    catch (error) {
+        host.setFileError(error instanceof Error ? error.message : String(error));
+        return int(-1n);
+    }
+}
 function ordinary(shim) {
     return { kind: "ordinary", shim };
 }
@@ -188,7 +204,7 @@ const SUSPENSION_ROUTES = {
     Accept: refused("Accept", true),
     SleepUntil: refused("SleepUntil"),
     ServiceAcquire: refused("ServiceAcquire"),
-    SemaphoreAcquire: refused("SemaphoreAcquire"),
+    SemaphoreAcquire: "SemaphoreAcquire",
     ActorSend: refused("ActorSend"),
     RestartWait: refused("RestartWait"),
     CallClosure: refused("CallClosure"),
@@ -519,6 +535,9 @@ const UNIT_FAMILIES = {
     ActorLink: refused("ActorLink"),
     ActorMonitor: refused("ActorMonitor"),
     ActorCaller: resumable({ handler: "actor_caller" }),
+    ContextActorId: resumable({ handler: "context_actor_id" }),
+    ContextSupervisor: resumable({ handler: "context_supervisor" }),
+    ContextTraceSpan: resumable({ handler: "context_trace_span" }),
     ActorRefusalLog: resumable({ handler: "actor_refusal_log" }),
     ActorUnlink: refused("ActorUnlink"),
     AutoMutexAlloc: refused("AutoMutexAlloc"),
@@ -533,14 +552,17 @@ const UNIT_FAMILIES = {
     ActorRequestRelease: refused("ActorRequestRelease"),
     ActorCallFree: refused("ActorCallFree"),
     ActorRequestTake: refused("ActorRequestTake"),
-    DurationAbs: refused("DurationAbs"),
-    DurationHours: refused("DurationHours"),
-    DurationIsZero: refused("DurationIsZero"),
-    DurationMicros: refused("DurationMicros"),
-    DurationMillis: refused("DurationMillis"),
-    DurationMins: refused("DurationMins"),
-    DurationNanos: refused("DurationNanos"),
-    DurationSecs: refused("DurationSecs"),
+    DurationAbs: (_host, args) => {
+        const nanos = integer(args, 0);
+        return int(nanos === -(1n << 63n) ? (1n << 63n) - 1n : nanos < 0n ? -nanos : nanos);
+    },
+    DurationHours: (_host, args) => int(integer(args, 0) / 3600000000000n),
+    DurationIsZero: (_host, args) => bool(integer(args, 0) === 0n),
+    DurationMicros: (_host, args) => int(integer(args, 0) / 1000n),
+    DurationMillis: (_host, args) => int(integer(args, 0) / 1000000n),
+    DurationMins: (_host, args) => int(integer(args, 0) / 60000000000n),
+    DurationNanos: (_host, args) => int(integer(args, 0)),
+    DurationSecs: (_host, args) => int(integer(args, 0) / 1000000000n),
     DynBoxAlloc: refused("DynBoxAlloc"),
     DynBoxFree: refused("DynBoxFree"),
     HashMapContainsKeyLayout: refused("HashMapContainsKeyLayout"),
@@ -567,9 +589,9 @@ const UNIT_FAMILIES = {
     HashSetNewWithLayout: refused("HashSetNewWithLayout"),
     HashSetRemoveLayout: refused("HashSetRemoveLayout"),
     HashSetToVecLayout: refused("HashSetToVecLayout"),
-    InstantDurationSince: refused("InstantDurationSince"),
-    InstantElapsed: refused("InstantElapsed"),
-    InstantNow: refused("InstantNow"),
+    InstantDurationSince: (_host, args) => int(saturatingI64(integer(args, 0) - integer(args, 1))),
+    InstantElapsed: (host, args) => int(saturatingI64(saturatingI64(host.monotonicTimeNanos()) - integer(args, 0))),
+    InstantNow: (host) => int(saturatingI64(host.monotonicTimeNanos())),
     NodeConnect: refused("NodeConnect"),
     NodeId: refused("NodeId"),
     NodeIdDisplay: refused("NodeIdDisplay"),
@@ -1065,8 +1087,23 @@ function bigMin(left, right) {
 function bigMax(left, right) {
     return right > left ? right : left;
 }
+function saturatingI64(value) {
+    return bigMax(-(1n << 63n), bigMin((1n << 63n) - 1n, value));
+}
 // ── externs ─────────────────────────────────────────────────────────────────
 const EXTERN_SHIMS = {
+    hew_semaphore_new: (host, args) => host.semaphores.create(integer(args, 0)),
+    hew_semaphore_clone: (host, args) => host.semaphores.clone(arg(args, 0)),
+    hew_semaphore_try_acquire: (host, args) => bool(host.semaphores.tryAcquire(arg(args, 0))),
+    hew_semaphore_count: (host, args) => int(host.semaphores.count(arg(args, 0))),
+    hew_semaphore_release: (host, args) => {
+        host.semaphores.release(arg(args, 0));
+        return UNIT;
+    },
+    hew_semaphore_free: (host, args) => {
+        host.semaphores.close(arg(args, 0));
+        return UNIT;
+    },
     hew_path_separator: () => str("/"),
     hew_calendar_format: {
         kind: "ordinary",
@@ -1116,7 +1153,9 @@ const EXTERN_SHIMS = {
         host.pipes.freePair(arg(args, 0));
         return UNIT;
     },
-    hew_stream_last_error: () => str(""),
+    hew_stream_last_error: (host) => host.fileError("LastError"),
+    hew_io_write: (host, args) => checkedWrite(host, text(args, 0), false),
+    hew_io_write_err: (host, args) => checkedWrite(host, text(args, 0), true),
     hew_regex_new: (host, args) => compileRegex(host, args),
     hew_regex_clone: (_host, args) => cloneValue(arg(args, 0)),
     // Releasing a handle the VM traces by reference is nothing to do.

package/dist/interpreter/v1/validate.js

@@ -209,7 +209,8 @@ export function admitPackage(pkg, bridges = {}) {
                 const id = term.operation.supervisor;
                 const supervisor = pkg.supervisors?.find((layout) => layout.id === id);
                 const config = term.args.length -
-                    (supervisor?.children.some((child) => child.is_pool) ? 1 : 0);
+                    (supervisor?.children.some((child) => child.is_pool) ? 1 : 0) -
+                    (supervisor?.backoff ? 2 : 0);
                 if (!supervisor ||
                     config < 0 ||
                     supervisor.children.some((child) => {

package/dist/interpreter/values.d.ts

@@ -15,7 +15,7 @@ export interface RcCell {
     owner: RcOwner | null;
     typeName: string;
 }
-export type VmValue = {
+export type VmValue = import("./v1/semaphores.js").SemaphoreHandle | {
     kind: "encoding";
     format: EncodingFormat;
     value: EncodingNode | null;

package/dist/interpreter/values.js

@@ -33,6 +33,10 @@ export function cloneValue(value) {
             return { kind: "weak", cell: value.cell, closed: false };
         case "host_resource":
             throw new Error("a filesystem owner cannot be copied");
+        case "semaphore":
+            // The opaque ABI pointer is copied for calls borrowing the enclosing
+            // affine Semaphore. Only its explicit clone operation creates an owner.
+            return value;
         case "timer":
             throw new Error("a timer cancellation handle cannot be copied");
         case "unit":
@@ -208,6 +212,8 @@ export function renderF64(value) {
 }
 export function renderStdout(value) {
     switch (value.kind) {
+        case "semaphore":
+            return "Semaphore";
         case "encoding":
             return JSON.stringify(value.value);
         case "host_resource":
@@ -269,6 +275,8 @@ export function renderStdout(value) {
 }
 export function toJsonValue(value) {
     switch (value.kind) {
+        case "semaphore":
+            return "Semaphore";
         case "encoding":
             return value.value;
         case "host_resource":

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "@hew-lang/sandbox-vm",
-  "version": "0.7.1",
+  "version": "0.9.1",
   "hewSource": {
-    "commit": "7b489ef7392ed3baced2a4d119e1e4741995ece2",
-    "tag": "v0.7.1",
+    "commit": "17e06579cb14a167be1e369bdda5388e14e95f80",
+    "tag": "v0.9.1",
     "dirty": false
   },
   "description": "Deterministic TypeScript interpreter for the Hew educational sandbox",
@@ -21,7 +21,7 @@
     "cli/"
   ],
   "dependencies": {
-    "@hew-lang/wasm": "0.7.1"
+    "@hew-lang/wasm": "0.9.1"
   },
   "keywords": [
     "hew",