@statespace-tech/sdk 0.0.0-stage → 0.1.1

package/dist/errors.d.ts

@@ -0,0 +1,18 @@
+export type JsonValue = null | boolean | number | string | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+export type JsonObject = {
+    [key: string]: JsonValue;
+};
+/** A request to Statespace failed or the client is misconfigured. */
+export declare class StatespaceError extends Error {
+}
+/** A request that retrying cannot fix. */
+export declare class PermanentError extends StatespaceError {
+}
+/** A component trapped or returned an invalid value. */
+export declare class FunctionError extends StatespaceError {
+}
+/** A component exceeded its timeout. */
+export declare class FunctionTimeout extends FunctionError {
+}

package/dist/errors.js

@@ -0,0 +1,12 @@
+/** A request to Statespace failed or the client is misconfigured. */
+export class StatespaceError extends Error {
+}
+/** A request that retrying cannot fix. */
+export class PermanentError extends StatespaceError {
+}
+/** A component trapped or returned an invalid value. */
+export class FunctionError extends StatespaceError {
+}
+/** A component exceeded its timeout. */
+export class FunctionTimeout extends FunctionError {
+}

package/dist/experiment.d.ts

@@ -0,0 +1,59 @@
+import { type Parameter } from './assignment.js';
+import type { Client } from './client.js';
+import { type JsonObject, type JsonValue } from './errors.js';
+/** The outcome recorded when a parameter falls back to the application's default. */
+export declare const ERROR_OUTCOME = "statespace.error";
+export interface AssignOptions {
+    /** The JSON the experiment's eligibility rule reads. */
+    context?: JsonObject;
+}
+export interface FunctionOptions {
+    /** The time limit for one call. Defaults to 5000. */
+    timeoutMs?: number;
+}
+/** One experiment. Get one with `experiment(name)`. */
+export declare class Experiment {
+    #private;
+    readonly name: string;
+    private constructor();
+    /** @internal */
+    static load(client: Client, name: string): Promise<Experiment>;
+    /** @internal Keep serving the last configuration when a refresh fails. */
+    refresh(): Promise<void>;
+    /**
+     * Assign a subject to a group and record the assignment. The same subject
+     * always gets the same group. While the experiment is not running, or for
+     * ineligible subjects, the group has no parameters, so every read returns
+     * the application's default.
+     */
+    assign(subjectId: string, options?: AssignOptions): Group;
+    /**
+     * Record an outcome, such as a click or a purchase, for a subject. Outcomes
+     * can come from any process; results count each one for the group the
+     * subject was assigned to before it.
+     */
+    log(subjectId: string, name: string, data?: JsonObject): void;
+    /** @internal */
+    execute(sha256: string, input: JsonValue, timeoutMs: number): Promise<JsonValue>;
+}
+/**
+ * The group a subject was assigned to. `name` is the group's name,
+ * `"control"`, or `null` when the subject is not in the experiment. Every read
+ * takes the application's default, which is returned for control, for
+ * parameters the group does not set, and when a value has the wrong type or
+ * a function fails.
+ */
+export declare class Group {
+    #private;
+    readonly name: string | null;
+    /** @internal */
+    constructor(experiment: Experiment, subjectId: string, name: string | null, parameters: Record<string, Parameter>);
+    /** The group's value for `name`, or `fallback`. */
+    value<T>(name: string, fallback: T): T;
+    /**
+     * The group's function for `name`, or `fallback`. The function takes and
+     * returns JSON values, runs locally in a sandbox, and falls back to
+     * `fallback` if it fails. Calls always return a promise.
+     */
+    function<I extends JsonValue, O extends JsonValue>(name: string, fallback: (input: I) => O | Promise<O>, options?: FunctionOptions): (input: I) => Promise<O>;
+}

package/dist/experiment.js

@@ -0,0 +1,190 @@
+// Experiments, assignments, and the parameter values a group receives.
+import { randomUUID } from 'node:crypto';
+import { bucket, choose, } from './assignment.js';
+import { FunctionTimeout, PermanentError, } from './errors.js';
+/** The outcome recorded when a parameter falls back to the application's default. */
+export const ERROR_OUTCOME = 'statespace.error';
+const DEFAULT_TIMEOUT_MILLISECONDS = 5_000;
+/** One experiment. Get one with `experiment(name)`. */
+export class Experiment {
+    name;
+    #client;
+    #config;
+    constructor(client, name, config) {
+        this.name = name;
+        this.#client = client;
+        this.#config = config;
+    }
+    /** @internal */
+    static async load(client, name) {
+        if (name.length === 0)
+            throw new RangeError('experiment name must not be empty');
+        try {
+            return new Experiment(client, name, await client.load(name));
+        }
+        catch (error) {
+            if (error instanceof PermanentError)
+                throw error;
+            console.warn(`statespace: serving defaults for ${name}: ${String(error)}`);
+            return new Experiment(client, name, undefined);
+        }
+    }
+    /** @internal Keep serving the last configuration when a refresh fails. */
+    async refresh() {
+        try {
+            this.#config = await this.#client.load(this.name);
+        }
+        catch (error) {
+            console.warn(`statespace: could not refresh ${this.name}: ${String(error)}`);
+        }
+    }
+    /**
+     * Assign a subject to a group and record the assignment. The same subject
+     * always gets the same group. While the experiment is not running, or for
+     * ineligible subjects, the group has no parameters, so every read returns
+     * the application's default.
+     */
+    assign(subjectId, options = {}) {
+        if (subjectId.length === 0)
+            throw new RangeError('subjectId must not be empty');
+        const context = structuredClone(options.context ?? {});
+        const config = this.#config;
+        if (config === undefined || config.status !== 'running') {
+            return new Group(this, subjectId, null, {});
+        }
+        if (Date.now() - config.fetchedAt > config.staleAfter) {
+            console.warn(`statespace: the ${this.name} configuration is stale; serving defaults`);
+            return new Group(this, subjectId, null, {});
+        }
+        let reason;
+        try {
+            reason = config.eligibility.evaluate(context) ? 'assigned' : 'ineligible';
+        }
+        catch (error) {
+            console.warn(`statespace: eligibility failed for ${this.name}: ${String(error)}`);
+            reason = 'eligibility-error';
+        }
+        const assigned = reason === 'assigned'
+            ? choose(config.groups, bucket(config.salt, subjectId))
+            : undefined;
+        this.#client.enqueue('run', {
+            id: `run_${randomUUID().replaceAll('-', '')}`,
+            experiment: config.name,
+            version: config.version,
+            subject_id: subjectId,
+            group: assigned?.name ?? null,
+            reason,
+            context,
+            timestamp: new Date().toISOString(),
+        });
+        return new Group(this, subjectId, assigned?.name ?? null, assigned?.parameters ?? {});
+    }
+    /**
+     * Record an outcome, such as a click or a purchase, for a subject. Outcomes
+     * can come from any process; results count each one for the group the
+     * subject was assigned to before it.
+     */
+    log(subjectId, name, data = {}) {
+        if (subjectId.length === 0 || name.length === 0) {
+            throw new RangeError('subjectId and name must not be empty');
+        }
+        this.#client.enqueue('outcome', {
+            id: `out_${randomUUID().replaceAll('-', '')}`,
+            experiment: this.name,
+            subject_id: subjectId,
+            name,
+            data,
+            timestamp: new Date().toISOString(),
+        });
+    }
+    /** @internal */
+    execute(sha256, input, timeoutMs) {
+        return this.#client.execute(sha256, input, timeoutMs);
+    }
+}
+/**
+ * The group a subject was assigned to. `name` is the group's name,
+ * `"control"`, or `null` when the subject is not in the experiment. Every read
+ * takes the application's default, which is returned for control, for
+ * parameters the group does not set, and when a value has the wrong type or
+ * a function fails.
+ */
+export class Group {
+    name;
+    #experiment;
+    #subjectId;
+    #parameters;
+    /** @internal */
+    constructor(experiment, subjectId, name, parameters) {
+        this.name = name;
+        this.#experiment = experiment;
+        this.#subjectId = subjectId;
+        this.#parameters = parameters;
+    }
+    /** The group's value for `name`, or `fallback`. */
+    value(name, fallback) {
+        const parameter = this.#parameters[name];
+        if (parameter === undefined)
+            return fallback;
+        if (parameter.kind !== 'value') {
+            this.#error(name, 'type', 'is a function; read it with function()');
+            return fallback;
+        }
+        if (!matches(parameter.value, fallback)) {
+            this.#error(name, 'type', `is not a ${kind(fallback)}`);
+            return fallback;
+        }
+        return parameter.value;
+    }
+    /**
+     * The group's function for `name`, or `fallback`. The function takes and
+     * returns JSON values, runs locally in a sandbox, and falls back to
+     * `fallback` if it fails. Calls always return a promise.
+     */
+    function(name, fallback, options = {}) {
+        const parameter = this.#parameters[name];
+        if (parameter === undefined)
+            return async (input) => fallback(input);
+        if (parameter.kind !== 'function' || parameter.sha256 === undefined) {
+            this.#error(name, 'type', 'is a value; read it with value()');
+            return async (input) => fallback(input);
+        }
+        const sha256 = parameter.sha256;
+        const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MILLISECONDS;
+        return async (input) => {
+            const started = performance.now();
+            try {
+                return (await this.#experiment.execute(sha256, input, timeoutMs));
+            }
+            catch (error) {
+                const failure = error instanceof FunctionTimeout ? 'timeout' : 'failed';
+                this.#error(name, failure, String(error), performance.now() - started);
+                return fallback(input);
+            }
+        };
+    }
+    #error(parameter, error, detail, durationMs) {
+        console.warn(`statespace: ${parameter} in ${this.name}: ${error} ${detail}`);
+        this.#experiment.log(this.#subjectId, ERROR_OUTCOME, {
+            group: this.name,
+            parameter,
+            error,
+            ...(durationMs === undefined
+                ? {}
+                : { duration_ms: Math.round(durationMs * 1000) / 1000 }),
+        });
+    }
+}
+function kind(value) {
+    if (value === null)
+        return 'null';
+    if (Array.isArray(value))
+        return 'array';
+    return typeof value;
+}
+/** Whether a JSON value can stand in for the fallback's type. */
+function matches(value, fallback) {
+    return (fallback === null ||
+        fallback === undefined ||
+        kind(value) === kind(fallback));
+}

package/dist/index.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Run Statespace experiments on parameter values and functions.
+ *
+ * ```ts
+ * import { experiment } from '@statespace-tech/sdk';
+ *
+ * const ranking = await experiment('ranking');
+ * const group = ranking.assign('u_42', { context: { country: 'US' } });
+ * const rank = group.function('ranker', rerank);
+ * const topK = group.value('top_k', 20);
+ * ranking.log('u_42', 'click');
+ * ```
+ */
+import type { Experiment } from './experiment.js';
+export { Client, type ClientOptions } from './client.js';
+export { type JsonObject, type JsonValue, StatespaceError } from './errors.js';
+export { type AssignOptions, ERROR_OUTCOME, Experiment, type FunctionOptions, Group, } from './experiment.js';
+/**
+ * The experiment `name` from the default client, which reads `SSP_API_KEY`
+ * and `STATESPACE_URL`, or the session saved by `ssp login`. Handles are
+ * cached, so call this anywhere.
+ */
+export declare function experiment(name: string): Promise<Experiment>;
+/** Wait until queued events are delivered. Resolves to false on timeout or loss. */
+export declare function flush(timeoutMs?: number): Promise<boolean>;

package/dist/index.js

@@ -0,0 +1,34 @@
+/**
+ * Run Statespace experiments on parameter values and functions.
+ *
+ * ```ts
+ * import { experiment } from '@statespace-tech/sdk';
+ *
+ * const ranking = await experiment('ranking');
+ * const group = ranking.assign('u_42', { context: { country: 'US' } });
+ * const rank = group.function('ranker', rerank);
+ * const topK = group.value('top_k', 20);
+ * ranking.log('u_42', 'click');
+ * ```
+ */
+import { Client } from './client.js';
+export { Client } from './client.js';
+export { StatespaceError } from './errors.js';
+export { ERROR_OUTCOME, Experiment, Group, } from './experiment.js';
+let defaultClient;
+function client() {
+    defaultClient ??= new Client();
+    return defaultClient;
+}
+/**
+ * The experiment `name` from the default client, which reads `SSP_API_KEY`
+ * and `STATESPACE_URL`, or the session saved by `ssp login`. Handles are
+ * cached, so call this anywhere.
+ */
+export function experiment(name) {
+    return client().experiment(name);
+}
+/** Wait until queued events are delivered. Resolves to false on timeout or loss. */
+export function flush(timeoutMs) {
+    return client().flush(timeoutMs);
+}

package/dist/memory.d.ts

@@ -0,0 +1,4 @@
+/** Limit each guest linear memory before native WebAssembly compilation. */
+export declare function memoryLimitPages(): number;
+export declare function capModuleMemory(bytes: Uint8Array, pages: number): Uint8Array<ArrayBuffer>;
+export declare function installImportedMemoryLimit(pages: number): void;

package/dist/memory.js

@@ -0,0 +1,85 @@
+/** Limit each guest linear memory before native WebAssembly compilation. */
+export function memoryLimitPages() {
+    const raw = process.env.STATESPACE_MAX_MEMORY_BYTES;
+    const bytes = raw === undefined ? NaN : Number(raw);
+    return Number.isSafeInteger(bytes) && bytes >= 65536
+        ? Math.min(65536, Math.floor(bytes / 65536))
+        : 4096;
+}
+export function capModuleMemory(bytes, pages) {
+    let offset = 8;
+    const read = () => {
+        let value = 0;
+        for (let index = 0; index < 5; index += 1) {
+            const byte = bytes[offset++];
+            if (byte === undefined)
+                throw new Error('truncated Wasm module');
+            value += (byte & 127) * 2 ** (7 * index);
+            if ((byte & 128) === 0) {
+                if (value > 0xffffffff)
+                    throw new Error('invalid Wasm integer');
+                return value;
+            }
+        }
+        throw new Error('invalid Wasm integer');
+    };
+    const encode = (value) => {
+        const result = [];
+        do {
+            const byte = value % 128;
+            value = Math.floor(value / 128);
+            result.push(byte | (value > 0 ? 128 : 0));
+        } while (value > 0);
+        return result;
+    };
+    const chunks = [bytes.slice(0, 8)];
+    while (offset < bytes.length) {
+        const start = offset;
+        const id = bytes[offset++];
+        const size = read();
+        const end = offset + size;
+        if (end > bytes.length)
+            throw new Error('truncated Wasm section');
+        if (id === 5) {
+            const count = read();
+            const payload = encode(count);
+            for (let index = 0; index < count; index += 1) {
+                const flags = read();
+                if (flags !== 0 && flags !== 1)
+                    throw new Error('unsupported Wasm memory type');
+                const minimum = read();
+                const maximum = flags === 1 ? read() : pages;
+                if (minimum > pages)
+                    throw new Error('Wasm memory exceeds configured limit');
+                payload.push(1, ...encode(minimum), ...encode(Math.min(maximum, pages)));
+            }
+            if (offset !== end)
+                throw new Error('invalid Wasm memory section');
+            chunks.push(Uint8Array.from([5, ...encode(payload.length), ...payload]));
+        }
+        else {
+            offset = end;
+            chunks.push(bytes.slice(start, end));
+        }
+    }
+    const result = new Uint8Array(chunks.reduce((size, chunk) => size + chunk.length, 0));
+    let destination = 0;
+    for (const chunk of chunks) {
+        result.set(chunk, destination);
+        destination += chunk.length;
+    }
+    return result;
+}
+export function installImportedMemoryLimit(pages) {
+    const OriginalMemory = WebAssembly.Memory;
+    WebAssembly.Memory = class extends OriginalMemory {
+        constructor(descriptor) {
+            if (descriptor.initial > pages)
+                throw new Error('Wasm memory exceeds configured limit');
+            super({
+                ...descriptor,
+                maximum: Math.min(descriptor.maximum ?? pages, pages),
+            });
+        }
+    };
+}

package/dist/runtime.d.ts

@@ -0,0 +1,7 @@
+import { type JsonValue } from './errors.js';
+/**
+ * Run a component's `execute` once in a worker thread, which is terminated
+ * when the timeout elapses. The guest has no filesystem, network, or
+ * environment access.
+ */
+export declare function executeComponent(bytes: Uint8Array, inputs: JsonValue, timeout: number): Promise<JsonValue>;

package/dist/runtime.js

@@ -0,0 +1,123 @@
+// Transpile Statespace components with jco and run them in worker threads.
+import { createHash } from 'node:crypto';
+import { rmSync } from 'node:fs';
+import { mkdtemp, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { Worker } from 'node:worker_threads';
+import { transpileBytes } from '@bytecodealliance/jco-transpile';
+import { FunctionError, FunctionTimeout } from './errors.js';
+const modules = new Map();
+const directories = new Set();
+process.once('exit', () => {
+    for (const directory of directories) {
+        rmSync(directory, { recursive: true, force: true });
+    }
+});
+const SUPPORTED_WASI_IMPORTS = new Set([
+    'wasi:cli/environment',
+    'wasi:cli/exit',
+    'wasi:cli/stdin',
+    'wasi:cli/stdout',
+    'wasi:cli/stderr',
+    'wasi:cli/terminal-input',
+    'wasi:cli/terminal-output',
+    'wasi:cli/terminal-stdin',
+    'wasi:cli/terminal-stdout',
+    'wasi:cli/terminal-stderr',
+    'wasi:io/error',
+    'wasi:io/poll',
+    'wasi:io/streams',
+    'wasi:clocks/monotonic-clock',
+    'wasi:clocks/wall-clock',
+    'wasi:random/random',
+    'wasi:filesystem/types',
+    'wasi:filesystem/preopens',
+]);
+async function modulePath(bytes) {
+    const hash = createHash('sha256').update(bytes).digest('hex');
+    let pending = modules.get(hash);
+    if (pending === undefined) {
+        pending = (async () => {
+            const result = await transpileBytes(bytes, {
+                name: 'component',
+                wasiShim: false,
+                instantiation: 'async',
+            });
+            for (const name of result.imports) {
+                if (!supportedWasiImport(name)) {
+                    throw new FunctionError(`component imports unsupported host capability: ${name}`);
+                }
+            }
+            const directory = await mkdtemp(join(tmpdir(), 'statespace-component-'));
+            directories.add(directory);
+            for (const [name, content] of Object.entries(result.files)) {
+                if (name.endsWith('.d.ts'))
+                    continue;
+                if (name.includes('/') || name.includes('\\') || name === '..') {
+                    throw new FunctionError('invalid transpiled component path');
+                }
+                await writeFile(join(directory, name), content);
+            }
+            const file = Object.keys(result.files).find((name) => name.endsWith('.js'));
+            if (file === undefined)
+                throw new FunctionError('component has no JavaScript binding');
+            await writeFile(join(directory, 'package.json'), '{"type":"module"}');
+            return join(directory, file);
+        })();
+        modules.set(hash, pending);
+        pending.catch(() => modules.delete(hash));
+    }
+    return pending;
+}
+function supportedWasiImport(name) {
+    return SUPPORTED_WASI_IMPORTS.has(name);
+}
+/**
+ * Run a component's `execute` once in a worker thread, which is terminated
+ * when the timeout elapses. The guest has no filesystem, network, or
+ * environment access.
+ */
+export async function executeComponent(bytes, inputs, timeout) {
+    const started = performance.now();
+    const path = await modulePath(bytes);
+    const remaining = timeout - (performance.now() - started);
+    if (remaining <= 0) {
+        throw new FunctionTimeout('component exceeded its timeout');
+    }
+    return new Promise((resolve, reject) => {
+        const worker = new Worker(new URL('./worker.js', import.meta.url), {
+            workerData: { path, input: JSON.stringify(inputs) },
+            execArgv: [],
+            stdin: true,
+            stdout: true,
+            stderr: true,
+        });
+        worker.stdin?.end();
+        worker.stdout.resume();
+        worker.stderr.resume();
+        let settled = false;
+        const finish = (error, value) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            void worker.terminate();
+            if (error !== undefined)
+                reject(error);
+            else
+                resolve(value ?? null);
+        };
+        const timer = setTimeout(() => finish(new FunctionTimeout('component exceeded its timeout')), remaining);
+        worker.once('message', (message) => {
+            if (message.error !== undefined)
+                finish(new FunctionError(message.error));
+            else
+                finish(undefined, message.value);
+        });
+        worker.once('error', (error) => finish(new FunctionError(error.message)));
+        worker.once('exit', (code) => {
+            finish(new FunctionError(`component worker exited with code ${code}`));
+        });
+    });
+}

package/dist/worker.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/worker.js

@@ -0,0 +1,34 @@
+import { readFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { parentPort, workerData } from 'node:worker_threads';
+import { WASIShim } from '@bytecodealliance/preview2-shim/instantiation';
+import { capModuleMemory, installImportedMemoryLimit, memoryLimitPages, } from './memory.js';
+async function run(task) {
+    const pages = memoryLimitPages();
+    installImportedMemoryLimit(pages);
+    const bindings = await import(pathToFileURL(task.path).href);
+    const getCoreModule = async (path) => {
+        if (path.includes('/') || path.includes('\\') || path === '..') {
+            throw new Error('invalid core module path');
+        }
+        return WebAssembly.compile(capModuleMemory(await readFile(join(dirname(task.path), path)), pages));
+    };
+    const wasi = new WASIShim({
+        sandbox: { preopens: {}, env: {}, args: [], enableNetwork: false },
+    });
+    const imports = wasi.getImportObject();
+    imports['wasi:cli/environment'] = {
+        getEnvironment: () => [],
+        getArguments: () => [],
+        initialCwd: () => undefined,
+    };
+    const instance = await bindings.instantiate(getCoreModule, imports);
+    if (typeof instance.execute !== 'function')
+        throw new Error('component has no execute export');
+    const output = await instance.execute(task.input);
+    if (typeof output !== 'string')
+        throw new Error('component returned a non-string value');
+    return JSON.parse(output);
+}
+void run(workerData).then((value) => parentPort?.postMessage({ value }), (error) => parentPort?.postMessage({ error: String(error) }));

package/package.json

@@ -1,6 +1,57 @@
 {
   "name": "@statespace-tech/sdk",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "Run Statespace A/B tests on functions and values in TypeScript and JavaScript applications",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "NOTICE"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "npm run build && vitest run",
+    "format": "prettier --write src test",
+    "format:check": "prettier --check src test",
+    "prepare": "npm run build"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/statespace-tech/typescript-sdk.git"
+  },
+  "homepage": "https://statespace.com",
+  "keywords": [
+    "ab-testing",
+    "experimentation",
+    "webassembly",
+    "agents"
+  ],
+  "license": "Apache-2.0",
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "@bytecodealliance/jco-transpile": "^0.15.0",
+    "@bytecodealliance/preview2-shim": "^0.26.0",
+    "@marcbachmann/cel-js": "^8.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "prettier": "3.9.6",
+    "typescript": "^5.9.0",
+    "vitest": "^4.0.0"
+  }
+}