@smthrs/harness 0.0.0-stage → 1.0.0-rc.4

package/dist/esm/QuickJSSandbox.d.ts

@@ -0,0 +1,151 @@
+/**
+ * The QuickJS-WASM sandbox binding.
+ *
+ * This is the production `Sandbox`: the cell runs inside a QuickJS interpreter
+ * compiled to WebAssembly, which is a genuinely separate JavaScript realm with
+ * no reference to the host's globals, prototypes, or module loader. The same
+ * single-file variant runs unmodified on Node and in a browser, so a browser
+ * host provides this layer and calls the identical harness.
+ *
+ * What the cell can reach is exactly `ctx`: `ctx.call` bridges to the host's
+ * durable flow boundary, `ctx.flows` is a frozen catalog projection. The
+ * prelude removes `Date` and `Math.random` from the realm, because a replayed
+ * cell must reach the same calls in the same order, and `Proxy`, because a
+ * value that answers reflection from a handler cannot be weighed against the
+ * run's memory ceiling. There is no filesystem, no network, no process, and no
+ * module loader to reach in the first place.
+ *
+ * Teardown is scope finalization and cancellation is fiber interruption: an
+ * interrupted frame disposes the runtime, which is the only thing holding the
+ * cell alive.
+ *
+ * Which QuickJS build is compiled is a seam. The default compiles the
+ * single-file build from bytes, which is what Node and a browser want. A host
+ * whose runtime forbids compiling WebAssembly from bytes at runtime, such as
+ * Cloudflare's workerd, provides {@link Variant} instead and names a build
+ * whose module came from its toolchain.
+ *
+ * @since 0.1.0
+ */
+import { Context, Effect, Layer } from "effect";
+import type { QuickJSSyncVariant, QuickJSWASMModule } from "quickjs-emscripten-core";
+import * as Sandbox from "./Sandbox.ts";
+/**
+ * Caches only a successful asynchronous load; a rejection may be retried.
+ *
+ * @category constructors
+ * @since 0.1.0
+ */
+export declare const cacheSuccessful: <A>(load: () => Promise<A>) => () => Promise<A>;
+/**
+ * The QuickJS build the sandbox compiles.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export interface VariantService {
+    readonly variant: QuickJSSyncVariant;
+}
+declare const Variant_base: Context.ServiceClass<Variant, "@smthrs/harness/QuickJSSandbox/Variant", VariantService>;
+/**
+ * The QuickJS build the sandbox compiles.
+ *
+ * @category services
+ * @since 0.1.0
+ */
+export declare class Variant extends Variant_base {
+}
+/**
+ * Provides the single-file build, which Node and a browser both compile.
+ *
+ * @category layers
+ * @since 0.1.0
+ */
+export declare const layerVariantLive: Layer.Layer<Variant>;
+/**
+ * Provides a build the host names.
+ *
+ * A workerd host builds one with `newVariant(baseVariant, { wasmModule })` from
+ * a `.wasm` module import, because that runtime instantiates a module the
+ * toolchain compiled and refuses to compile one from bytes.
+ *
+ * @category layers
+ * @since 0.1.0
+ */
+export declare const layerVariant: (variant: QuickJSSyncVariant) => Layer.Layer<Variant>;
+/**
+ * Synchronous monotonic-enough clock required by QuickJS's interrupt callback.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export interface ComputeClockService {
+    readonly now: () => number;
+}
+declare const ComputeClock_base: Context.ServiceClass<ComputeClock, "@smthrs/harness/QuickJSSandbox/ComputeClock", ComputeClockService>;
+/**
+ * Synchronous monotonic-enough clock required by QuickJS's interrupt callback.
+ *
+ * @category services
+ * @since 0.1.0
+ */
+export declare class ComputeClock extends ComputeClock_base {
+}
+/**
+ * Provides the browser-safe host clock behind the QuickJS clock seam.
+ *
+ * @category layers
+ * @since 0.1.0
+ */
+export declare const layerClockLive: Layer.Layer<ComputeClock>;
+/**
+ * Loads a QuickJS module through the sandbox's typed failure boundary.
+ *
+ * @category constructors
+ * @since 0.1.0
+ */
+export declare const loadModule: (loader: () => Promise<QuickJSWASMModule>) => Effect.Effect<QuickJSWASMModule, Sandbox.SandboxError>;
+/**
+ * Constructs the QuickJS sandbox over the build the host names, compiling the
+ * WebAssembly module once.
+ *
+ * @category constructors
+ * @since 0.1.0
+ */
+export declare const makeWithVariant: Effect.Effect<Sandbox.Sandbox, Sandbox.SandboxError, ComputeClock | Variant>;
+/**
+ * Constructs the QuickJS sandbox over the single-file build.
+ *
+ * The build is fixed here rather than left in the requirements, so the clock
+ * stays the only seam this constructor asks its caller to fill. A host that
+ * names its own build uses {@link makeWithVariant}.
+ *
+ * @category constructors
+ * @since 0.1.0
+ * @slop
+ */
+export declare const makeWithClock: Effect.Effect<Sandbox.Sandbox, Sandbox.SandboxError, ComputeClock>;
+/**
+ * Constructs the QuickJS sandbox with the live clock layer.
+ *
+ * @category constructors
+ * @since 0.1.0
+ */
+export declare const make: Effect.Effect<Sandbox.Sandbox, Sandbox.SandboxError>;
+/**
+ * Provides the QuickJS sandbox over the build the host names.
+ *
+ * @category layers
+ * @since 0.1.0
+ */
+export declare const layerWithVariant: Layer.Layer<Sandbox.Sandbox, Sandbox.SandboxError, Variant>;
+/**
+ * Provides the QuickJS sandbox over the single-file build.
+ *
+ * @category layers
+ * @since 0.1.0
+ * @slop
+ */
+export declare const layer: Layer.Layer<Sandbox.Sandbox, Sandbox.SandboxError>;
+export {};
+//# sourceMappingURL=QuickJSSandbox.d.ts.map

package/dist/esm/QuickJSSandbox.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"QuickJSSandbox.d.ts","sourceRoot":"","sources":["../../src/QuickJSSandbox.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAGH,OAAO,EAAE,OAAO,EAAY,MAAM,EAAE,KAAK,EAA8B,MAAM,QAAQ,CAAA;AACrF,OAAO,KAAK,EAIV,kBAAkB,EAClB,iBAAiB,EAClB,MAAM,yBAAyB,CAAA;AAQhC,OAAO,KAAK,OAAO,MAAM,cAAc,CAAA;AAgWvC;;;;;GAKG;AACH,eAAO,MAAM,eAAe,GAAI,CAAC,EAAE,MAAM,MAAM,OAAO,CAAC,CAAC,CAAC,KAAG,MAAM,OAAO,CAAC,CAAC,CAY1E,CAAA;AAED;;;;;GAKG;AACH,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,OAAO,EAAE,kBAAkB,CAAA;CACrC;;AAED;;;;;GAKG;AACH,qBAAa,OAAQ,SAAQ,YAE5B;CAAG;AAEJ;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB,EAAE,KAAK,CAAC,KAAK,CAAC,OAAO,CAAmD,CAAA;AAErG;;;;;;;;;GASG;AACH,eAAO,MAAM,YAAY,GAAI,SAAS,kBAAkB,KAAG,KAAK,CAAC,KAAK,CAAC,OAAO,CAAwC,CAAA;AAkBtH;;;;;GAKG;AACH,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,GAAG,EAAE,MAAM,MAAM,CAAA;CAC3B;;AAED;;;;;GAKG;AACH,qBAAa,YAAa,SAAQ,iBAEjC;CAAG;AAEJ;;;;;GAKG;AACH,eAAO,MAAM,cAAc,EAAE,KAAK,CAAC,KAAK,CAAC,YAAY,CAA0D,CAAA;AAi9B/G;;;;;GAKG;AACH,eAAO,MAAM,UAAU,GACrB,QAAQ,MAAM,OAAO,CAAC,iBAAiB,CAAC,KACvC,MAAM,CAAC,MAAM,CAAC,iBAAiB,EAAE,OAAO,CAAC,YAAY,CASpD,CAAA;AAEJ;;;;;;GAMG;AACH,eAAO,MAAM,eAAe,EAAE,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,OAAO,EAAE,OAAO,CAAC,YAAY,EAAE,YAAY,GAAG,OAAO,CASrG,CAAA;AAEJ;;;;;;;;;;GAUG;AACH,eAAO,MAAM,aAAa,EAAE,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,OAAO,EAAE,OAAO,CAAC,YAAY,EAAE,YAAY,CAE5F,CAAA;AAED;;;;;GAKG;AACH,eAAO,MAAM,IAAI,EAAE,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,OAAO,EAAE,OAAO,CAAC,YAAY,CAErE,CAAA;AAED;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB,EAAE,KAAK,CAAC,KAAK,CAAC,OAAO,CAAC,OAAO,EAAE,OAAO,CAAC,YAAY,EAAE,OAAO,CAElC,CAAA;AAEvD;;;;;;GAMG;AACH,eAAO,MAAM,KAAK,EAAE,KAAK,CAAC,KAAK,CAAC,OAAO,CAAC,OAAO,EAAE,OAAO,CAAC,YAAY,CAAuC,CAAA"}