@plexspaces/sdk 0.1.1

package/dist/actor_id.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Parsed form of a canonical PlexSpaces actor ID.
+ *
+ * Canonical string format: {name}//{actor_type}::{namespace}@{node_id}
+ */
+export declare class ActorID {
+    /** Unique instance identifier (role name or ULID). */
+    readonly name: string;
+    /** Behavior type registered in the application (e.g. 'budget_manager'). */
+    readonly actorType: string;
+    /** Application namespace (e.g. 'go-resource-aware-inference'). */
+    readonly namespace: string;
+    /** Node hosting the actor (e.g. 'test-node-8091'). Empty string if absent. */
+    readonly nodeId: string;
+    constructor(name: string, actorType: string, namespace: string, nodeId: string);
+    /**
+     * Parse a canonical actor ID string into an ActorID.
+     *
+     * Expected format: {name}//{actor_type}::{namespace}@{node_id}
+     * Throws if the string does not contain the expected separators.
+     */
+    static parse(id: string): ActorID;
+    /** Return the canonical actor ID string: {name}//{actor_type}::{namespace}@{node_id}. */
+    toString(): string;
+    /**
+     * Return a copy with an explicit actor type and name.
+     *
+     * Use this to build a canonical ID for a peer actor with the given type and name,
+     * keeping the same namespace and node.
+     *
+     * For supervisor-spawned actors with stable role names (name == type == role):
+     * ```ts
+     * const peer = self.withTypeAndName("budget_manager", "budget_manager");
+     * ```
+     *
+     * For actors where name and type differ (e.g. ULID-named workers of a shared type):
+     * ```ts
+     * const peer = self.withTypeAndName("inference_worker", ulid);
+     * ```
+     */
+    withTypeAndName(actorType: string, name: string): ActorID;
+    /** Return a copy with a different name. */
+    withName(name: string): ActorID;
+    /** Return a copy with a different name and actor_type. */
+    withType(name: string, actorType: string): ActorID;
+}

package/dist/actor_id.js

@@ -0,0 +1,85 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Copyright (C) 2025 PlexSpaces Contributors
+//
+// ActorID — parsed representation of a canonical PlexSpaces actor ID.
+//
+// Canonical format: {name}//{actor_type}::{namespace}@{node_id}
+//
+// The name is typically a stable role name for supervisor-spawned actors,
+// or a ULID for dynamically spawned actors.
+//
+// Usage — peer/sibling discovery from within a WASM actor:
+//
+//   const selfID = ActorID.parse(host.selfId());
+//   const budgetID = selfID.sibling("budget_manager");
+//   const reply = await host.ask(budgetID.toString(), payload, 5000);
+/**
+ * Parsed form of a canonical PlexSpaces actor ID.
+ *
+ * Canonical string format: {name}//{actor_type}::{namespace}@{node_id}
+ */
+export class ActorID {
+    constructor(name, actorType, namespace, nodeId) {
+        this.name = name;
+        this.actorType = actorType;
+        this.namespace = namespace;
+        this.nodeId = nodeId;
+    }
+    /**
+     * Parse a canonical actor ID string into an ActorID.
+     *
+     * Expected format: {name}//{actor_type}::{namespace}@{node_id}
+     * Throws if the string does not contain the expected separators.
+     */
+    static parse(id) {
+        const slashIdx = id.indexOf("//");
+        if (slashIdx < 0) {
+            throw new Error(`parseActorID: missing '//' in ${JSON.stringify(id)}`);
+        }
+        const name = id.slice(0, slashIdx);
+        const rest = id.slice(slashIdx + 2); // "{actor_type}::{namespace}@{node_id}"
+        // Split on "@" to separate type::namespace from node_id
+        const atIdx = rest.indexOf("@");
+        const nodeId = atIdx >= 0 ? rest.slice(atIdx + 1) : "";
+        const typeNs = atIdx >= 0 ? rest.slice(0, atIdx) : rest;
+        // Split on "::" to separate actor_type from namespace
+        const colonIdx = typeNs.indexOf("::");
+        const actorType = colonIdx >= 0 ? typeNs.slice(0, colonIdx) : typeNs;
+        const namespace = colonIdx >= 0 ? typeNs.slice(colonIdx + 2) : "";
+        return new ActorID(name, actorType, namespace, nodeId);
+    }
+    /** Return the canonical actor ID string: {name}//{actor_type}::{namespace}@{node_id}. */
+    toString() {
+        if (this.nodeId) {
+            return `${this.name}//${this.actorType}::${this.namespace}@${this.nodeId}`;
+        }
+        return `${this.name}//${this.actorType}::${this.namespace}`;
+    }
+    /**
+     * Return a copy with an explicit actor type and name.
+     *
+     * Use this to build a canonical ID for a peer actor with the given type and name,
+     * keeping the same namespace and node.
+     *
+     * For supervisor-spawned actors with stable role names (name == type == role):
+     * ```ts
+     * const peer = self.withTypeAndName("budget_manager", "budget_manager");
+     * ```
+     *
+     * For actors where name and type differ (e.g. ULID-named workers of a shared type):
+     * ```ts
+     * const peer = self.withTypeAndName("inference_worker", ulid);
+     * ```
+     */
+    withTypeAndName(actorType, name) {
+        return new ActorID(name, actorType, this.namespace, this.nodeId);
+    }
+    /** Return a copy with a different name. */
+    withName(name) {
+        return new ActorID(name, this.actorType, this.namespace, this.nodeId);
+    }
+    /** Return a copy with a different name and actor_type. */
+    withType(name, actorType) {
+        return new ActorID(name, actorType, this.namespace, this.nodeId);
+    }
+}

package/dist/decorators.d.ts

@@ -0,0 +1,40 @@
+export type BehaviorType = 'GenServer' | 'GenEvent' | 'GenStateMachine' | 'Workflow';
+export type InvocationType = 'call' | 'cast';
+export interface HandlerMetadata {
+    methodName: string;
+    msgTypes: string[];
+    invocation: InvocationType;
+}
+export interface ActorDefinitionMetadata {
+    behaviorType: BehaviorType;
+    facets: string[];
+    handlers: Record<string, HandlerMetadata>;
+    runHandler?: string;
+    signalHandlers: Record<string, string>;
+    queryHandlers: Record<string, string>;
+    fsmStates?: string[];
+    fsmInitial?: string;
+}
+export declare function actor(options?: {
+    facets?: string[];
+}): <T extends Function>(target: T) => T;
+export declare function gen_server_actor(options?: {
+    facets?: string[];
+}): <T extends Function>(target: T) => T;
+export declare function event_actor(options?: {
+    facets?: string[];
+}): <T extends Function>(target: T) => T;
+export declare function fsm_actor(options?: {
+    facets?: string[];
+    states?: string[];
+    initial?: string;
+}): <T extends Function>(target: T) => T;
+export declare function workflow_actor(options?: {
+    facets?: string[];
+}): <T extends Function>(target: T) => T;
+export declare function handler(...msgTypes: string[]): (target: object, propertyKey: string, _descriptor: PropertyDescriptor) => void;
+export declare const init_handler: typeof handler;
+export declare function run_handler(target: object, propertyKey: string, _descriptor: PropertyDescriptor): void;
+export declare function signal_handler(...names: string[]): (target: object, propertyKey: string, _descriptor: PropertyDescriptor) => void;
+export declare function query_handler(...names: string[]): (target: object, propertyKey: string, _descriptor: PropertyDescriptor) => void;
+export declare function getActorDefinition(target: object): ActorDefinitionMetadata | undefined;

package/dist/decorators.js

@@ -0,0 +1,97 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Copyright (C) 2025 PlexSpaces Contributors
+const ACTOR_METADATA = Symbol.for('plexspaces.actor.metadata');
+function ensureMetadata(target) {
+    const ctor = typeof target === 'function' ? target : target.constructor;
+    const existing = Reflect.get(ctor, ACTOR_METADATA);
+    if (existing)
+        return existing;
+    const created = {
+        behaviorType: 'GenServer',
+        facets: [],
+        handlers: {},
+        signalHandlers: {},
+        queryHandlers: {},
+    };
+    Reflect.set(ctor, ACTOR_METADATA, created);
+    return created;
+}
+function actorDecorator(behaviorType, facets = []) {
+    return function (target) {
+        const metadata = ensureMetadata(target);
+        metadata.behaviorType = behaviorType;
+        metadata.facets = [...facets];
+        return target;
+    };
+}
+export function actor(options = {}) {
+    return actorDecorator('GenServer', options.facets ?? []);
+}
+export function gen_server_actor(options = {}) {
+    return actorDecorator('GenServer', options.facets ?? []);
+}
+export function event_actor(options = {}) {
+    return actorDecorator('GenEvent', options.facets ?? []);
+}
+export function fsm_actor(options = {}) {
+    return function (target) {
+        const result = actorDecorator('GenStateMachine', options.facets ?? [])(target);
+        if (options.states !== undefined || options.initial !== undefined) {
+            const metadata = ensureMetadata(result);
+            if (options.states !== undefined)
+                metadata.fsmStates = [...options.states];
+            if (options.initial !== undefined)
+                metadata.fsmInitial = options.initial;
+        }
+        return result;
+    };
+}
+export function workflow_actor(options = {}) {
+    return actorDecorator('Workflow', options.facets ?? []);
+}
+export function handler(...msgTypes) {
+    let invocation = 'call';
+    const effectiveTypes = msgTypes.filter((value) => {
+        if (value === 'call' || value === 'cast') {
+            invocation = value;
+            return false;
+        }
+        return true;
+    });
+    return function (target, propertyKey, _descriptor) {
+        const metadata = ensureMetadata(target);
+        const entry = {
+            methodName: propertyKey,
+            msgTypes: effectiveTypes,
+            invocation,
+        };
+        for (const msgType of effectiveTypes) {
+            metadata.handlers[msgType] = entry;
+        }
+    };
+}
+export const init_handler = handler;
+export function run_handler(target, propertyKey, _descriptor) {
+    const metadata = ensureMetadata(target);
+    metadata.runHandler = propertyKey;
+}
+export function signal_handler(...names) {
+    return function (target, propertyKey, _descriptor) {
+        const metadata = ensureMetadata(target);
+        for (const name of names) {
+            metadata.signalHandlers[name] = propertyKey;
+        }
+    };
+}
+export function query_handler(...names) {
+    return function (target, propertyKey, _descriptor) {
+        const metadata = ensureMetadata(target);
+        for (const name of names) {
+            metadata.queryHandlers[name] = propertyKey;
+        }
+    };
+}
+export function getActorDefinition(target) {
+    const ctor = typeof target === 'function' ? target : target.constructor;
+    return Reflect.get(ctor, ACTOR_METADATA);
+}

package/dist/host.d.ts

@@ -0,0 +1,312 @@
+import { ObjectType as RegistryObjectType } from './wire/registry-proto-wire.js';
+/**
+ * Tuple space helper: list-in, list-out API.
+ * Use null in patterns for wildcards. Consistent with Python host.ts and Go host.TS().
+ */
+export declare class TupleSpace {
+    private host;
+    constructor(host: Host);
+    /**
+     * Write a tuple. Values are encoded as plexspaces.tuplespace.v1 WriteRequest protobuf wire
+     * (same as Go `TupleSpace.Write` / Rust simple_component_host).
+     */
+    write(tuple: unknown[]): string;
+    /** Take one matching tuple (destructive). */
+    take(pattern: unknown[]): unknown[] | null;
+    /** Read one matching tuple (non-destructive). */
+    read(pattern: unknown[]): unknown[] | null;
+    /** Read all matching tuples (non-destructive). */
+    readAll(pattern: unknown[]): unknown[][];
+}
+/**
+ * Process groups sub-API.
+ * broadcast(group, msgType, payload): msgType is used by the host for routing; payload can be data-only.
+ */
+export declare class ProcessGroups {
+    /** Join a named process group */
+    join(group: string): void;
+    /** Leave a named process group */
+    leave(group: string): void;
+    /** Get members of a process group */
+    members(group: string): string[];
+    /** Broadcast to all group members. msgType is used for routing so payload can be data-only. */
+    broadcast(group: string, msgType: string, payload?: unknown): void;
+    /** Return the first member of a process group, or null if empty. */
+    first(group: string): string | null;
+    /** Return the first member of a process group, throwing if empty. */
+    firstOrThrow(group: string): string;
+}
+/**
+ * PlexSpaces host function interface.
+ *
+ * Provides typed access to all WIT host capabilities.
+ *
+ * Usage:
+ *   import { host } from '@plexspaces/sdk';
+ *
+ *   host.send('other-actor', 'ping', { data: 'hello' });
+ *   const response = host.ask('other-actor', 'get_balance', {}, 5000);
+ *   const myId = host.selfId();
+ */
+/** Object registration data from the registry. */
+export interface ObjectRegistration {
+    objectId: string;
+    objectType: string;
+    grpcAddress?: string;
+    objectCategory?: string;
+    tenantId?: string;
+    namespace?: string;
+    capabilities?: string[];
+    labels?: string[];
+    healthStatus?: string;
+    createdAt?: number;
+    updatedAt?: number;
+    lastHeartbeat?: number;
+    alias?: string;
+}
+/**
+ * Object Registry host functions for registration and discovery.
+ *
+ * All calls encode request/response as proto wire bytes matching
+ * plexspaces.object_registry.v1 messages.
+ *
+ * @example
+ * ```typescript
+ * // Register this actor
+ * host.registry.register({ objectId: myId, objectType: 'actor', objectCategory: 'GenServer' });
+ *
+ * // Look up by alias (Orleans grain directory pattern)
+ * const reg = host.registry.lookupByAlias('Counter:my-counter:default:tenant1');
+ *
+ * // Discover all actors of a given category
+ * const actors = host.registry.discover({ objectType: RegistryObjectType.ACTOR, objectCategory: 'GenServer' });
+ * ```
+ */
+export declare class Registry {
+    /**
+     * Register an object in the registry.
+     */
+    register(reg: ObjectRegistration): void;
+    /**
+     * Unregister an object from the registry.
+     */
+    unregister(objectId: string, objectType: number, tenantId?: string, namespace?: string): void;
+    /**
+     * Look up an object by ID. Returns null if not found, throws on storage errors.
+     */
+    lookup(objectId: string, objectType?: number, tenantId?: string, namespace?: string): ObjectRegistration | null;
+    /**
+     * Look up an object by alias (Orleans grain directory pattern).
+     * Alias format: "{actor_type}:{name}:{namespace}:{tenant_id}"
+     * Returns null if not found, throws on storage errors.
+     */
+    lookupByAlias(alias: string): ObjectRegistration | null;
+    /**
+     * Discover objects with optional filtering.
+     */
+    discover(options?: {
+        objectType?: number;
+        objectCategory?: string;
+        tenantId?: string;
+        namespace?: string;
+        capabilities?: string[];
+        labels?: string[];
+        pageSize?: number;
+    }): ObjectRegistration[];
+    /**
+     * Update the heartbeat for a registered object.
+     */
+    heartbeat(objectId: string, objectType?: number, tenantId?: string, namespace?: string): void;
+}
+export { RegistryObjectType };
+export declare class Host {
+    readonly processGroups: ProcessGroups;
+    /** Tuple space: list-in, list-out. Use null in patterns for wildcards. */
+    readonly ts: TupleSpace;
+    /** Object registry: register, discover, and look up actors and services. */
+    readonly registry: Registry;
+    /** Send message to another actor (fire-and-forget) */
+    send(to: string, msgType: string, payload?: unknown): string;
+    /** Send request and wait for response (request-reply) */
+    ask(to: string, msgType: string, payload?: unknown, timeoutMs?: number): unknown;
+    /** Get own actor ID */
+    selfId(): string;
+    /**
+     * Spawn a new actor through the framework-owned actor spawn path exposed by the host.
+     * @param moduleRef - Actor type/module reference (must be deployed)
+     * @param actorId - Unique ID for the new actor (empty = auto-generated ULID)
+     * @param initConfig - Optional config passed to the new actor's init()
+     * @returns Spawned actor ID string (may be auto-generated if actorId was empty)
+     */
+    spawn(moduleRef: string, actorId?: string, initConfig?: unknown): string;
+    /** Stop an actor gracefully */
+    stop(actorId: string): void;
+    /** Bidirectional link */
+    link(actorId: string): void;
+    /** Remove bidirectional link */
+    unlink(actorId: string): void;
+    /** Monitor an actor (returns monitor reference) */
+    monitor(actorId: string): string;
+    /** Cancel a monitor */
+    demonitor(monitorRef: string): void;
+    /**
+     * Send message to self after delay (returns timer ID for tracking).
+     * Timer cancellation is managed by the framework's TimerFacet/ReminderFacet.
+     * Stop the actor to cancel pending timers.
+     *
+     * WIT `payload` is opaque bytes; pass UTF-8 JSON bytes so the host matches Go/Rust guest JSON.
+     */
+    sendAfter(delayMs: number, msgType: string, payload?: unknown): string;
+    /** Log a message */
+    log(level: string, message: string): void;
+    debug(message: string): void;
+    info(message: string): void;
+    warn(message: string): void;
+    error(message: string): void;
+    /** Get current timestamp in milliseconds */
+    nowMs(): number;
+    kvGet(key: string): string;
+    kvPut(key: string, value: string): string;
+    kvDelete(key: string): string;
+    kvList(prefix: string): string;
+    /** Retrieve a JSON value by key. Returns parsed object or null if not found. */
+    kvGetJson<T = unknown>(key: string): T | null;
+    /** Serialize value to JSON and store under key. Throws on write failure. */
+    kvPutJson(key: string, value: unknown): void;
+    /** Increment a single named application metric counter by 1. Errors are swallowed. */
+    incrCounter(applicationId: string, name: string): void;
+    /** Increment one or more named application metric counters. Errors are swallowed. */
+    incrCounters(applicationId: string, counters: Record<string, number>): void;
+    /** @internal TupleSpace — plexspaces.tuplespace.v1 wire bytes. */
+    tsWritePayload(data: Uint8Array): string;
+    /** @internal */
+    tsReadPayload(data: Uint8Array): Uint8Array;
+    /** @internal */
+    tsTakePayload(data: Uint8Array): Uint8Array;
+    /** @internal */
+    tsReadAllPayload(data: Uint8Array): Uint8Array;
+    lockAcquire(tenantId: string, namespace: string, holderId: string, lockName: string, leaseDurationSecs?: number, timeoutMs?: number): string;
+    lockRelease(lockId: string, tenantId: string, namespace: string, holderId: string, lockVersion: string): string;
+    lockRenew(lockId: string, tenantId: string, namespace: string, holderId: string, lockVersion: string, leaseDurationSecs?: number): string;
+    blobUpload(blobId: string, data: string, contentType?: string): string;
+    blobDownload(blobId: string): string;
+    blobDelete(blobId: string): string;
+    blobList(prefix: string): string;
+    /**
+     * Checkout an actor from a named pool. Returns handle { actor_id, pool_name, checkout_id } or null on failure.
+     */
+    poolCheckout(poolName: string, timeoutMs?: number): {
+        actor_id: string;
+        pool_name: string;
+        checkout_id: string;
+    } | null;
+    /**
+     * Checkin an actor to the pool. Pass actor_id and checkout_id from the handle returned by poolCheckout.
+     */
+    poolCheckin(poolName: string, actorId: string, checkoutId: string, healthy: boolean): void;
+    /**
+     * Get pool metrics (total_actors, available_actors, busy_actors, current_load, etc.). Returns null if not available.
+     */
+    poolGetMetrics(poolName: string): Record<string, unknown> | null;
+    createShardGroup(request: Record<string, unknown>): Record<string, unknown>;
+    bulkUpdateShardGroup(request: Record<string, unknown>): Record<string, unknown>;
+    mapShardGroup(request: Record<string, unknown>): Record<string, unknown>;
+    scatterGather(request: Record<string, unknown>): Record<string, unknown>;
+    broadcastShardGroup(request: Record<string, unknown>): Record<string, unknown>;
+    reduceShardGroup(request: Record<string, unknown>): Record<string, unknown>;
+    allReduceShardGroup(request: Record<string, unknown>): Record<string, unknown>;
+    barrierShardGroup(request: Record<string, unknown>): Record<string, unknown>;
+    spawnActors(request: Record<string, unknown>): Record<string, unknown>;
+    applicationMetricsAdd(applicationId: string, metrics: Record<string, unknown>): Record<string, unknown>;
+    applicationGetMetrics(applicationId: string, nodeId: string): Record<string, unknown>;
+    applicationGetStatus(applicationId: string, nodeId: string): Record<string, unknown>;
+    /**
+     * Execute an outbound HTTP request via a named service link.
+     *
+     * The link must be pre-configured in RuntimeConfig.service_links.
+     * The host handles retries, circuit breaking, and auth injection.
+     *
+     * @param linkName  Service link name (e.g. "payments-api")
+     * @param method    HTTP method ("GET", "POST", "PUT", "DELETE", "PATCH")
+     * @param pathAndQuery  Path and optional query string (e.g. "/v1/users?limit=10")
+     * @param headers   Optional extra headers object
+     * @param body      Optional request body string (JSON or base64-encoded bytes)
+     * @returns Response object with status, headers, body
+     */
+    httpFetch(linkName: string, method: string, pathAndQuery: string, headers?: Record<string, string>, body?: string): {
+        status: number;
+        headers: Record<string, string>;
+        body: string;
+    };
+}
+/**
+ * Two-cursor monotonic append-only log backed by KV.
+ *
+ * Embed in actor state (serialize with `JSON.stringify`). Each consumer
+ * tracks its own read cursor so they advance independently.
+ *
+ * @example
+ * ```typescript
+ * const log = new EventLog();
+ * const seq = log.append(host, 'audit:', { action: 'login' });
+ * const [events, newCursor] = log.poll(host, 'audit:', 'consumer-1', 20);
+ * ```
+ */
+export declare class EventLog {
+    watermark: number;
+    constructor(watermark?: number);
+    /** Append an entry to the log. Returns the assigned sequence number. */
+    append(h: Host, prefix: string, entry: unknown): number;
+    /**
+     * Return up to `limit` events for `consumerId` that arrived after its last cursor.
+     * Returns `[events, newCursor]`. The new cursor is persisted in KV.
+     */
+    poll(h: Host, prefix: string, consumerId: string, limit?: number): [unknown[], number];
+}
+/**
+ * Ergonomic outbound HTTP client backed by a named service link.
+ *
+ * The link must be pre-configured in RuntimeConfig.service_links.
+ * The host handles retries, circuit breaking, and auth injection.
+ *
+ * @example
+ * ```typescript
+ * const http = new ServiceHttpClient("payments-api");
+ * const balance = http.get("/v1/balance?account=123");
+ * const result = http.post("/v1/transfer", { amount: 100 });
+ * ```
+ */
+export declare class ServiceHttpClient {
+    private readonly linkName;
+    constructor(linkName: string);
+    /** GET request. Returns response object with status, headers, body. */
+    get(pathAndQuery: string, headers?: Record<string, string>): {
+        status: number;
+        headers: Record<string, string>;
+        body: string;
+    };
+    /** POST JSON request. body is serialized to JSON. */
+    post(pathAndQuery: string, body?: unknown, headers?: Record<string, string>): {
+        status: number;
+        headers: Record<string, string>;
+        body: string;
+    };
+    /** PUT JSON request. */
+    put(pathAndQuery: string, body?: unknown, headers?: Record<string, string>): {
+        status: number;
+        headers: Record<string, string>;
+        body: string;
+    };
+    /** DELETE request. */
+    delete(pathAndQuery: string, headers?: Record<string, string>): {
+        status: number;
+        headers: Record<string, string>;
+        body: string;
+    };
+}
+/** Global host instance */
+export declare const host: Host;
+/** Return the first member of a process group, or null if empty. */
+export declare function pgFirst(group: string): string | null;
+/** Return the first member of a process group, throwing if empty. */
+export declare function pgFirstOrThrow(group: string): string;