@hew-lang/sandbox-vm 0.7.1 → 0.8.0

package/dist/interpreter/v1/exec.js

@@ -16,6 +16,7 @@ import { StructuralRenderer } from "./structural.js";
 import { timestampBinary } from "./timestamp.js";
 import { selectedValue, collectionOperation, sharedOperation, } from "./value-operations.js";
 import { Pipes } from "./pipes.js";
+import { Semaphores } from "./semaphores.js";
 import { FrameScheduler } from "./scheduler.js";
 import { DeterministicIds } from "../../scheduler/ids.js";
 import { Mt19937 } from "./mt19937.js";
@@ -128,6 +129,7 @@ class ExecutorV1 {
     rootFault = null;
     pkg;
     directories;
+    semaphores;
     constructor(admission, trace, stdin, policy, options) {
         this.trace = trace;
         this.stdin = stdin;
@@ -136,6 +138,7 @@ class ExecutorV1 {
         this.pkg = pkg;
         this.directories = new BrowserDirectories(options.directoryRoots);
         this.scheduler = new FrameScheduler(trace, policy);
+        this.semaphores = new Semaphores((nanos, ready) => this.scheduler.after(nanos, ready));
         this.ids = new DeterministicIds(trace.replay.seed);
         this.host = {
             argv: [...(options.argv ?? ["main.hew"])],
@@ -168,6 +171,7 @@ class ExecutorV1 {
                 }
             },
             pipes: this.pipes,
+            semaphores: this.semaphores,
             generatorStream: (value) => {
                 const id = this.ids.channel();
                 this.generatorStreams.set(id, {
@@ -2080,6 +2084,25 @@ class ExecutorV1 {
                 }
                 return;
             }
+            case "SemaphoreAcquire": {
+                const handle = this.boundary(act, term.inputs[0]);
+                const timeout = term.detail.operation === "AcquireTimeout"
+                    ? this.boundary(act, term.inputs[1])
+                    : null;
+                if (timeout !== null && timeout.kind !== "i64")
+                    throw new Error("semaphore timeout must be an integer");
+                let operation;
+                const wake = this.park(act, term, () => { }, () => operation?.take());
+                operation = this.semaphores.acquire(handle, timeout?.value ?? null, (acquired) => {
+                    wake(timeout === null ? UNIT : { kind: "bool", value: acquired });
+                });
+                const cancel = act.context.cancel;
+                act.context.cancel = (fault) => {
+                    operation?.cancel();
+                    cancel?.(fault);
+                };
+                return;
+            }
             case "Sleep": {
                 const duration = term.inputs[0]
                     ? this.boundary(act, term.inputs[0])
@@ -2113,7 +2136,7 @@ class ExecutorV1 {
                 message: `local actor wait cycle at ${operation}: ${path.map((actor) => actor.identity).join(" -> ")}`,
             });
     }
-    park(act, term, cleanup = () => { }) {
+    park(act, term, cleanup = () => { }, accepted = () => { }) {
         this.running = false;
         act.context.parked = true;
         let pending = null;
@@ -2138,6 +2161,7 @@ class ExecutorV1 {
                             : term.unwind);
                     }
                     else {
+                        accepted();
                         if (term.result && term.result !== "never")
                             this.define(act, term.result.value, outcome.value);
                         const edge = term.resumes[outcome.edge];
@@ -2480,6 +2504,9 @@ class ExecutorV1 {
                             value.cell.weak -= 1;
                         }
                         break;
+                    case "semaphore":
+                        this.semaphores.close(value);
+                        break;
                     case "host_resource": {
                         if (value.owner.closed)
                             break;

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

@@ -16,6 +16,7 @@ export interface ShimHost {
     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;
@@ -209,6 +210,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

@@ -188,7 +188,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"),
@@ -533,14 +533,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"),
@@ -1067,6 +1070,18 @@ function bigMax(left, right) {
 }
 // ── 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",

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.8.0",
   "hewSource": {
-    "commit": "7b489ef7392ed3baced2a4d119e1e4741995ece2",
-    "tag": "v0.7.1",
+    "commit": "9322b962e46f92cc9c595b7cf742f73202751d1a",
+    "tag": "v0.8.0",
     "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.8.0"
   },
   "keywords": [
     "hew",