@plexspaces/sdk 0.1.9 → 0.1.11

package/dist/host.d.ts

@@ -1,3 +1,4 @@
+import type { CreateShardGroupOptions, CreateShardGroupResult, ScatterGatherOptions, ScatterGatherResult, BroadcastShardGroupOptions, ReduceShardGroupOptions, AllReduceShardGroupOptions, BarrierShardGroupOptions, MapShardGroupOptions, BulkUpdateShardGroupOptions } from './shard_types.js';
 import { ObjectType as RegistryObjectType } from './wire/registry-proto-wire.js';
 /**
  * Tuple space helper: list-in, list-out API.
@@ -192,6 +193,61 @@ export declare class ActorRef {
  * Equivalent to Cloudflare: `const room = env.CHAT_ROOM.get(roomId)`
  */
 export declare function getActorRef(actorType: string, name: string, namespace: string): ActorRef;
+/**
+ * Message received from a channel, with payload decoded to a JS value.
+ */
+export interface ChannelMessage {
+    id: string;
+    msgType: string;
+    payload: unknown;
+    timestamp: number;
+    deliveryCount: number;
+    headers: Record<string, string>;
+}
+/**
+ * Channel host functions for queue and pub/sub messaging patterns.
+ *
+ * Channels unify queue (one consumer) and pub/sub (all subscribers) under
+ * a single API. The provider (InMemory, Redis, Kafka, etc.) is a runtime concern.
+ *
+ * Parity with Python `host.channel` and Go `host.Ch()`.
+ */
+export declare class Channel {
+    /** Send a message to a channel (queue semantics). Returns message ID. */
+    send(channelName: string, msgType: string, payload?: unknown): string;
+    /** Send with delay, TTL, and custom headers. Returns message ID. */
+    sendWithOptions(channelName: string, msgType: string, payload?: unknown, delayMs?: number, ttlMs?: number, headers?: Record<string, string>): string;
+    /** Receive one message from a channel. Returns null on timeout/empty. */
+    receive(channelName: string, timeoutMs?: number): ChannelMessage | null;
+    /** Publish a message to a channel (pub/sub — all subscribers receive). Returns message ID. */
+    publish(channelName: string, msgType: string, payload?: unknown): string;
+    /** Subscribe to a channel (pub/sub). Returns subscription ID. */
+    subscribe(channelName: string, filter?: string): string;
+    /** Cancel a subscription by ID. */
+    unsubscribe(subscriptionId: string): void;
+    /** Acknowledge successful processing (prevents redelivery). */
+    ack(channelName: string, messageId: string): void;
+    /** Negative-acknowledge a message. requeue=true retries; false sends to dead-letter. */
+    nack(channelName: string, messageId: string, requeue?: boolean): void;
+    /** Create a channel if it does not exist. maxSize=0 means unbounded. */
+    create(channelName: string, maxSize?: number, messageTtlMs?: number): void;
+    /** Delete a channel and all pending messages. */
+    delete(channelName: string): void;
+    /** Return the number of pending (unacked) messages in a channel. */
+    depth(channelName: string): number;
+}
+/**
+ * Outbox host functions for flow-controlled message dispatch.
+ *
+ * Messages are enqueued in a DB-backed channel and delivered asynchronously
+ * at AIMD-controlled concurrency. Parity with Python `host.outbox` and Go `host.Outbox()`.
+ */
+export declare class Outbox {
+    /** Dispatch messages to target actors via the outbox relay. Returns [accepted, rejected]. */
+    dispatch(ctx: string, dispatcherID: string, targetActorIDs: string[], payload: Uint8Array, messageType?: string, idempotencyKey?: string, conflictResolution?: string): [number, number];
+    /** Get current status of a dispatcher. Returns JSON-encoded status string. */
+    status(ctx: string, dispatcherID: string): string;
+}
 export declare class Host {
     readonly processGroups: ProcessGroups;
     /** Tuple space: list-in, list-out. Use null in patterns for wildcards. */
@@ -206,6 +262,10 @@ export declare class Host {
     readonly locks: LockClient;
     /** Blob storage client: host.blob.upload(), host.blob.download() etc. */
     readonly blob: BlobClient;
+    /** Channel client for queue and pub/sub messaging. */
+    readonly channel: Channel;
+    /** Outbox client for flow-controlled messaging. */
+    readonly outbox: Outbox;
     /**
      * Create an ergonomic HTTP client for a named service link.
      *
@@ -298,14 +358,14 @@ export declare class Host {
      * 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>;
+    createShardGroup(request: CreateShardGroupOptions): CreateShardGroupResult;
+    bulkUpdateShardGroup(request: BulkUpdateShardGroupOptions): Record<string, unknown>;
+    mapShardGroup(request: MapShardGroupOptions): Record<string, unknown>;
+    scatterGather(request: ScatterGatherOptions): ScatterGatherResult;
+    broadcastShardGroup(request: BroadcastShardGroupOptions): Record<string, unknown>;
+    reduceShardGroup(request: ReduceShardGroupOptions): Record<string, unknown>;
+    allReduceShardGroup(request: AllReduceShardGroupOptions): Record<string, unknown>;
+    barrierShardGroup(request: BarrierShardGroupOptions): 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>;

package/dist/host.js

@@ -8,7 +8,7 @@
 // Protobuf wire for WIT `payload` fields (matches Go WASM hostWire* / tuplespace_proto_wire).
 import { decodeReadResponseAllTuples, decodeReadResponseFirstTuple, encodeReadRequest, encodeWriteRequest, } from './wire/tuplespace-proto-wire.js';
 import { decodeHttpFetchResponseWire, encodeHttpFetchRequestWire } from './wire/http-fetch-proto-wire.js';
-import { decodeApplicationMetrics, decodeCreateShardGroupResponse, decodeGetApplicationStatusResponse, decodeScatterGatherResponse, encodeApplicationMetrics, encodeCreateShardGroupRequest, encodeScatterGatherRequest, } from './wire/shard-group-proto-wire.js';
+import { decodeApplicationMetrics, decodeBulkUpdateShardGroupResponse, decodeCreateShardGroupResponse, decodeGetApplicationStatusResponse, decodeScatterGatherResponse, encodeApplicationMetrics, encodeBulkUpdateShardGroupRequest, encodeCreateShardGroupRequest, encodeScatterGatherRequest, encodeBroadcastShardGroupRequest, decodeBroadcastShardGroupResponse, encodeReduceShardGroupRequest, decodeReduceShardGroupResponse, encodeAllReduceShardGroupRequest, decodeAllReduceShardGroupResponse, encodeBarrierShardGroupRequest, decodeBarrierShardGroupResponse, encodeMapShardGroupRequest, decodeMapShardGroupResponse, } from './wire/shard-group-proto-wire.js';
 import { decodeWitPayloadUtf8, encodeWitPayloadUtf8 } from './wit-payload.js';
 import { encodeRegisterRequest, encodeUnregisterRequest, encodeLookupRequest, encodeDiscoverRequest, encodeHeartbeatRequest, decodeLookupResponse, decodeDiscoverResponse, ObjectType as RegistryObjectType, } from './wire/registry-proto-wire.js';
 import { firstGroupMember, firstGroupMemberOrThrow } from './process_groups.js';
@@ -24,6 +24,8 @@ import { blobUpload as hostBlobUpload, blobDownload as hostBlobDownload, blobDel
 import { poolCheckout as hostPoolCheckout, poolCheckin as hostPoolCheckin, poolGetMetrics as hostPoolGetMetrics, } from 'plexspaces:actor/host-pool@0.1.0';
 import { createShardGroup as hostCreateShardGroup, bulkUpdateShardGroup as hostBulkUpdateShardGroup, mapShardGroup as hostMapShardGroup, broadcastShardGroup as hostBroadcastShardGroup, reduceShardGroup as hostReduceShardGroup, allReduceShardGroup as hostAllReduceShardGroup, barrierShardGroup as hostBarrierShardGroup, scatterGather as hostScatterGather, spawnActors as hostSpawnActors, applicationMetricsAdd as hostApplicationMetricsAdd, applicationGetMetrics as hostApplicationGetMetrics, applicationGetStatus as hostApplicationGetStatus, } from 'plexspaces:actor/host-shard@0.1.0';
 import { httpFetch as hostHttpFetch } from 'plexspaces:actor/host-http@0.1.0';
+import { channelSend as hostChannelSend, channelSendWithOptions as hostChannelSendWithOptions, channelReceive as hostChannelReceive, channelPublish as hostChannelPublish, channelSubscribe as hostChannelSubscribe, channelUnsubscribe as hostChannelUnsubscribe, channelAck as hostChannelAck, channelNack as hostChannelNack, channelCreate as hostChannelCreate, channelDelete as hostChannelDelete, channelDepth as hostChannelDepth, } from 'plexspaces:actor/channels@0.1.0';
+import { outboxDispatch as hostOutboxDispatch, outboxStatus as hostOutboxStatus, } from 'plexspaces:actor/outbox@0.1.0';
 import { register as hostRegistryRegister, unregister as hostRegistryUnregister, lookup as hostRegistryLookup, lookupByAlias as hostRegistryLookupByAlias, discover as hostRegistryDiscover, heartbeat as hostRegistryHeartbeat, } from 'plexspaces:actor/registry@0.1.0';
 /**
  * Safe call helper — returns empty string if function is undefined.
@@ -543,6 +545,176 @@ export class ActorRef {
 export function getActorRef(actorType, name, namespace) {
     return new ActorRef(actorType, name, namespace);
 }
+/**
+ * Channel host functions for queue and pub/sub messaging patterns.
+ *
+ * Channels unify queue (one consumer) and pub/sub (all subscribers) under
+ * a single API. The provider (InMemory, Redis, Kafka, etc.) is a runtime concern.
+ *
+ * Parity with Python `host.channel` and Go `host.Ch()`.
+ */
+export class Channel {
+    /** Send a message to a channel (queue semantics). Returns message ID. */
+    send(channelName, msgType, payload) {
+        const payloadBytes = encodeWitPayloadUtf8(payload !== undefined ? JSON.stringify(payload) : '{}');
+        const result = safeCall(hostChannelSend, '', channelName, msgType, payloadBytes);
+        if (typeof result === 'string' && result.startsWith('ERROR:')) {
+            throw new Error(result);
+        }
+        return result;
+    }
+    /** Send with delay, TTL, and custom headers. Returns message ID. */
+    sendWithOptions(channelName, msgType, payload, delayMs = 0, ttlMs = 0, headers) {
+        const payloadBytes = encodeWitPayloadUtf8(payload !== undefined ? JSON.stringify(payload) : '{}');
+        const headersJson = JSON.stringify(headers ?? {});
+        const result = safeCall(hostChannelSendWithOptions, '', channelName, msgType, payloadBytes, BigInt(delayMs), BigInt(ttlMs), headersJson);
+        if (typeof result === 'string' && result.startsWith('ERROR:')) {
+            throw new Error(result);
+        }
+        return result;
+    }
+    /** Receive one message from a channel. Returns null on timeout/empty. */
+    receive(channelName, timeoutMs = 0) {
+        const raw = safeCall(hostChannelReceive, '', channelName, BigInt(timeoutMs));
+        if (!raw || raw === '' || raw === undefined)
+            return null;
+        if (typeof raw === 'string') {
+            if (raw.startsWith('ERROR:'))
+                throw new Error(raw);
+            try {
+                return JSON.parse(raw);
+            }
+            catch {
+                return null;
+            }
+        }
+        const msg = raw;
+        if (!msg || !msg.id)
+            return null;
+        let decodedPayload;
+        try {
+            const payloadStr = decodeWitPayloadUtf8(msg.payload);
+            decodedPayload = JSON.parse(payloadStr);
+        }
+        catch {
+            decodedPayload = msg.payload;
+        }
+        const hdrs = {};
+        if (Array.isArray(msg.headers)) {
+            for (const [k, v] of msg.headers) {
+                hdrs[k] = v;
+            }
+        }
+        return {
+            id: msg.id,
+            msgType: msg.msgType,
+            payload: decodedPayload,
+            timestamp: typeof msg.timestamp === 'bigint' ? Number(msg.timestamp) : Number(msg.timestamp ?? 0),
+            deliveryCount: msg.deliveryCount,
+            headers: hdrs,
+        };
+    }
+    /** Publish a message to a channel (pub/sub — all subscribers receive). Returns message ID. */
+    publish(channelName, msgType, payload) {
+        const payloadBytes = encodeWitPayloadUtf8(payload !== undefined ? JSON.stringify(payload) : '{}');
+        const result = safeCall(hostChannelPublish, '', channelName, msgType, payloadBytes);
+        if (typeof result === 'string' && result.startsWith('ERROR:')) {
+            throw new Error(result);
+        }
+        return result;
+    }
+    /** Subscribe to a channel (pub/sub). Returns subscription ID. */
+    subscribe(channelName, filter = '') {
+        const result = safeCall(hostChannelSubscribe, '', channelName, filter);
+        if (typeof result === 'string' && result.startsWith('ERROR:')) {
+            throw new Error(result);
+        }
+        return result;
+    }
+    /** Cancel a subscription by ID. */
+    unsubscribe(subscriptionId) {
+        const result = safeCall(hostChannelUnsubscribe, subscriptionId);
+        if (typeof result === 'string' && result.startsWith('ERROR:')) {
+            throw new Error(result);
+        }
+    }
+    /** Acknowledge successful processing (prevents redelivery). */
+    ack(channelName, messageId) {
+        const result = safeCall(hostChannelAck, '', channelName, messageId);
+        if (typeof result === 'string' && result.startsWith('ERROR:')) {
+            throw new Error(result);
+        }
+    }
+    /** Negative-acknowledge a message. requeue=true retries; false sends to dead-letter. */
+    nack(channelName, messageId, requeue = true) {
+        const result = safeCall(hostChannelNack, '', channelName, messageId, requeue);
+        if (typeof result === 'string' && result.startsWith('ERROR:')) {
+            throw new Error(result);
+        }
+    }
+    /** Create a channel if it does not exist. maxSize=0 means unbounded. */
+    create(channelName, maxSize = 0, messageTtlMs = 0) {
+        const result = safeCall(hostChannelCreate, '', channelName, maxSize, BigInt(messageTtlMs));
+        if (typeof result === 'string' && result.startsWith('ERROR:')) {
+            throw new Error(result);
+        }
+    }
+    /** Delete a channel and all pending messages. */
+    delete(channelName) {
+        const result = safeCall(hostChannelDelete, '', channelName);
+        if (typeof result === 'string' && result.startsWith('ERROR:')) {
+            throw new Error(result);
+        }
+    }
+    /** Return the number of pending (unacked) messages in a channel. */
+    depth(channelName) {
+        const result = safeCall(hostChannelDepth, '', channelName);
+        if (typeof result === 'bigint')
+            return Number(result);
+        if (typeof result === 'number')
+            return result;
+        if (typeof result === 'string') {
+            if (result.startsWith('ERROR:'))
+                throw new Error(result);
+            const n = parseInt(result, 10);
+            return isNaN(n) ? 0 : n;
+        }
+        return 0;
+    }
+}
+/**
+ * Outbox host functions for flow-controlled message dispatch.
+ *
+ * Messages are enqueued in a DB-backed channel and delivered asynchronously
+ * at AIMD-controlled concurrency. Parity with Python `host.outbox` and Go `host.Outbox()`.
+ */
+export class Outbox {
+    /** Dispatch messages to target actors via the outbox relay. Returns [accepted, rejected]. */
+    dispatch(ctx, dispatcherID, targetActorIDs, payload, messageType = 'cast', idempotencyKey = '', conflictResolution = '') {
+        const result = safeCall(hostOutboxDispatch, ctx, dispatcherID, targetActorIDs, payload, messageType, idempotencyKey, conflictResolution);
+        if (typeof result === 'string' && result.startsWith('ERROR:')) {
+            throw new Error(result);
+        }
+        if (typeof result === 'string' && result.length > 0) {
+            try {
+                const parsed = JSON.parse(result);
+                return [parsed.accepted ?? 0, parsed.rejected ?? 0];
+            }
+            catch (_) {
+                return [0, 0];
+            }
+        }
+        return [0, 0];
+    }
+    /** Get current status of a dispatcher. Returns JSON-encoded status string. */
+    status(ctx, dispatcherID) {
+        const result = safeCall(hostOutboxStatus, ctx, dispatcherID);
+        if (typeof result === 'string' && result.startsWith('ERROR:')) {
+            throw new Error(result);
+        }
+        return typeof result === 'string' ? result : '';
+    }
+}
 export class Host {
     constructor() {
         this.processGroups = new ProcessGroups();
@@ -558,6 +730,10 @@ export class Host {
         this.locks = new LockClient();
         /** Blob storage client: host.blob.upload(), host.blob.download() etc. */
         this.blob = new BlobClient();
+        /** Channel client for queue and pub/sub messaging. */
+        this.channel = new Channel();
+        /** Outbox client for flow-controlled messaging. */
+        this.outbox = new Outbox();
     }
     /**
      * Create an ergonomic HTTP client for a named service link.
@@ -799,71 +975,170 @@ export class Host {
         }
     }
     createShardGroup(request) {
-        const reqBytes = encodeCreateShardGroupRequest(request);
+        const wireReq = {
+            group_id: request.groupId,
+            actor_type: request.actorType,
+            shard_count: request.shardCount,
+            partition_strategy: request.partitionStrategy ?? 'hash',
+            rebalance_policy: request.rebalancePolicy ?? 'manual',
+            placement: request.placement ? {
+                strategy: request.placement.strategy ?? 'from_registry',
+                node_ids: request.placement.nodeIds ?? [],
+                cluster: request.placement.cluster ?? '',
+            } : undefined,
+            initial_state: request.initialState,
+            metadata: request.metadata,
+        };
+        const reqBytes = encodeCreateShardGroupRequest(wireReq);
         const result = safeCall(hostCreateShardGroup, reqBytes);
         if (typeof result === 'string' && result.startsWith('ERROR:')) {
             throw new Error(result);
         }
         const bytes = hostPayloadToBytes(result);
         if (bytes.length === 0)
-            return { shard_actor_ids: [] };
+            return { groupId: '', actorType: '', shardActorIds: [], shardCount: 0 };
         const decoded = decodeCreateShardGroupResponse(bytes);
-        // Flatten: expose group fields at top level for actor convenience
         const group = decoded.group ?? {};
-        return { ...group, ...decoded };
+        const config = (group.config ?? {});
+        return {
+            groupId: config.group_id ?? '',
+            actorType: group.actor_type ?? '',
+            shardActorIds: group.shard_actor_ids ?? [],
+            shardCount: config.shard_count ?? 0,
+        };
     }
     bulkUpdateShardGroup(request) {
-        const result = safeCall(hostBulkUpdateShardGroup, JSON.stringify(request));
+        const wireReq = {
+            group_id: request.groupId,
+            updates: request.updates,
+            consistency_level: request.consistencyLevel === 'strong' ? 2 : request.consistencyLevel === 'sequential' ? 3 : 1,
+            timeout_ms: request.timeoutMs ?? 5000,
+            wait_for_responses: request.waitForResponses ?? false,
+        };
+        const reqBytes = encodeBulkUpdateShardGroupRequest(wireReq);
+        const result = safeCall(hostBulkUpdateShardGroup, reqBytes);
         if (typeof result === 'string' && result.startsWith('ERROR:')) {
             throw new Error(result);
         }
-        return JSON.parse(result);
+        const bytes = hostPayloadToBytes(result);
+        if (bytes.length === 0)
+            return { updates_sent: 0, updates_succeeded: 0, updates_failed: 0, errors: [] };
+        return decodeBulkUpdateShardGroupResponse(bytes);
     }
     mapShardGroup(request) {
-        const result = safeCall(hostMapShardGroup, JSON.stringify(request));
+        const wireReq = {
+            group_id: request.groupId,
+            map_function: request.mapFunction,
+            timeout_ms: request.timeoutMs ?? 30000,
+            min_responses: request.minResponses ?? 0,
+        };
+        const reqBytes = encodeMapShardGroupRequest(wireReq);
+        const result = safeCall(hostMapShardGroup, reqBytes);
         if (typeof result === 'string' && result.startsWith('ERROR:')) {
             throw new Error(result);
         }
-        return JSON.parse(result);
+        const bytes = hostPayloadToBytes(result);
+        if (bytes.length === 0)
+            return { shard_results: [] };
+        return decodeMapShardGroupResponse(bytes);
     }
     scatterGather(request) {
-        const reqBytes = encodeScatterGatherRequest(request);
+        const wireReq = {
+            group_id: request.groupId,
+            query: request.query,
+            aggregation: request.aggregation ?? 'concat',
+            timeout_ms: request.timeoutMs ?? 30000,
+            min_responses: request.minResponses ?? 0,
+        };
+        const reqBytes = encodeScatterGatherRequest(wireReq);
         const result = safeCall(hostScatterGather, reqBytes);
         if (typeof result === 'string' && result.startsWith('ERROR:')) {
             throw new Error(result);
         }
         const bytes = hostPayloadToBytes(result);
         if (bytes.length === 0)
-            return { shard_responses: [] };
-        return decodeScatterGatherResponse(bytes);
+            return { shardResponses: [] };
+        const decoded = decodeScatterGatherResponse(bytes);
+        return { shardResponses: decoded.shard_responses.map(r => ({
+                shardId: r.shard_id ?? 0,
+                shardActorId: r.shard_actor_id ?? '',
+                payload: r.payload ?? {},
+                success: r.success ?? false,
+                error: r.error ?? '',
+            })) };
     }
     broadcastShardGroup(request) {
-        const result = safeCall(hostBroadcastShardGroup, JSON.stringify(request));
+        const wireReq = {
+            group_id: request.groupId,
+            message: request.message,
+            timeout_ms: request.timeoutMs ?? 30000,
+            min_acks: request.minAcks ?? 0,
+        };
+        const reqBytes = encodeBroadcastShardGroupRequest(wireReq);
+        const result = safeCall(hostBroadcastShardGroup, reqBytes);
         if (typeof result === 'string' && result.startsWith('ERROR:')) {
             throw new Error(result);
         }
-        return JSON.parse(result);
+        const bytes = hostPayloadToBytes(result);
+        if (bytes.length === 0)
+            return { shard_responses: [] };
+        return decodeBroadcastShardGroupResponse(bytes);
     }
     reduceShardGroup(request) {
-        const result = safeCall(hostReduceShardGroup, JSON.stringify(request));
+        const wireReq = {
+            group_id: request.groupId,
+            map_function: request.mapFunction,
+            reduction: request.reduction,
+            target: request.target,
+            timeout_ms: request.timeoutMs ?? 30000,
+            min_responses: request.minResponses ?? 0,
+        };
+        const reqBytes = encodeReduceShardGroupRequest(wireReq);
+        const result = safeCall(hostReduceShardGroup, reqBytes);
         if (typeof result === 'string' && result.startsWith('ERROR:')) {
             throw new Error(result);
         }
-        return JSON.parse(result);
+        const bytes = hostPayloadToBytes(result);
+        if (bytes.length === 0)
+            return { shard_responses: [] };
+        return decodeReduceShardGroupResponse(bytes);
     }
     allReduceShardGroup(request) {
-        const result = safeCall(hostAllReduceShardGroup, JSON.stringify(request));
+        const wireReq = {
+            group_id: request.groupId,
+            map_function: request.mapFunction,
+            reduction: request.reduction,
+            target: request.target,
+            timeout_ms: request.timeoutMs ?? 30000,
+            min_responses: request.minResponses ?? 0,
+        };
+        const reqBytes = encodeAllReduceShardGroupRequest(wireReq);
+        const result = safeCall(hostAllReduceShardGroup, reqBytes);
         if (typeof result === 'string' && result.startsWith('ERROR:')) {
             throw new Error(result);
         }
-        return JSON.parse(result);
+        const bytes = hostPayloadToBytes(result);
+        if (bytes.length === 0)
+            return { shard_responses: [] };
+        return decodeAllReduceShardGroupResponse(bytes);
     }
     barrierShardGroup(request) {
-        const result = safeCall(hostBarrierShardGroup, JSON.stringify(request));
+        const wireReq = {
+            group_id: request.groupId,
+            barrier_id: request.barrierId,
+            round: request.round ?? 0,
+            timeout_ms: request.timeoutMs ?? 30000,
+            min_acks: request.minAcks ?? 0,
+        };
+        const reqBytes = encodeBarrierShardGroupRequest(wireReq);
+        const result = safeCall(hostBarrierShardGroup, reqBytes);
         if (typeof result === 'string' && result.startsWith('ERROR:')) {
             throw new Error(result);
         }
-        return JSON.parse(result);
+        const bytes = hostPayloadToBytes(result);
+        if (bytes.length === 0)
+            return { shard_responses: [] };
+        return decodeBarrierShardGroupResponse(bytes);
     }
     spawnActors(request) {
         const result = safeCall(hostSpawnActors, JSON.stringify(request));

package/dist/index.d.ts

@@ -1,10 +1,12 @@
 export { PlexSpacesActor, WorkflowActor } from "./actor.js";
 export { decodeWitPayloadUtf8, encodeWitPayloadUtf8 } from "./wit-payload.js";
 export { actor, gen_server_actor, event_actor, fsm_actor, workflow_actor, handler, init_handler, run_handler, signal_handler, query_handler, getActorDefinition, } from "./decorators.js";
-export { Host, ProcessGroups, TupleSpace, host, pgFirst, pgFirstOrThrow, ServiceHttpClient, ActorRef, getActorRef } from "./host.js";
+export { Host, ProcessGroups, TupleSpace, Channel, Outbox, host, pgFirst, pgFirstOrThrow, ServiceHttpClient, ActorRef, getActorRef } from "./host.js";
+export type { ChannelMessage } from "./host.js";
 export { ActorRouter } from "./router.js";
 export { defaultRetryConfig, withRetry, type RetryConfig, } from "./workflow.js";
 export { LeaderWorkerClient, listWorkerNodeIds, } from "./leader_worker.js";
 export { ActorID } from "./actor_id.js";
+export type { CreateShardGroupOptions, CreateShardGroupResult, ScatterGatherOptions, ScatterGatherResult, ShardQueryResult, BroadcastShardGroupOptions, ReduceShardGroupOptions, AllReduceShardGroupOptions, BarrierShardGroupOptions, MapShardGroupOptions, BulkUpdateShardGroupOptions, NodePlacementOptions, } from "./shard_types.js";
 export { WsThinClient, type ThinClientOptions, type ThinNodePingResult, } from "./ws_thin_client.js";
 export { AgentLoop, agentActor, defaultAgentConfig, type AgentConfig, type AgentStep, type AgentTrajectory, type AgentStepKind, } from "./agent.js";

package/dist/index.js

@@ -7,7 +7,7 @@
 export { PlexSpacesActor, WorkflowActor } from "./actor.js";
 export { decodeWitPayloadUtf8, encodeWitPayloadUtf8 } from "./wit-payload.js";
 export { actor, gen_server_actor, event_actor, fsm_actor, workflow_actor, handler, init_handler, run_handler, signal_handler, query_handler, getActorDefinition, } from "./decorators.js";
-export { Host, ProcessGroups, TupleSpace, host, pgFirst, pgFirstOrThrow, ServiceHttpClient, ActorRef, getActorRef } from "./host.js";
+export { Host, ProcessGroups, TupleSpace, Channel, Outbox, host, pgFirst, pgFirstOrThrow, ServiceHttpClient, ActorRef, getActorRef } from "./host.js";
 export { ActorRouter } from "./router.js";
 export { defaultRetryConfig, withRetry, } from "./workflow.js";
 export { LeaderWorkerClient, listWorkerNodeIds, } from "./leader_worker.js";

package/dist/shard_types.d.ts

@@ -0,0 +1,76 @@
+export interface NodePlacementOptions {
+    strategy?: 'from_registry' | 'same_node' | 'node_ids';
+    nodeIds?: string[];
+    cluster?: string;
+    requiredLabels?: Record<string, string>;
+    avoidNodeIds?: string[];
+    affinityLabels?: Record<string, string>;
+}
+export interface CreateShardGroupOptions {
+    groupId: string;
+    actorType: string;
+    shardCount: number;
+    partitionStrategy?: 'hash' | 'range' | 'consistent_hash';
+    rebalancePolicy?: 'manual' | 'on_scale' | 'load_based';
+    placement?: NodePlacementOptions;
+    initialState?: Record<string, unknown>;
+    metadata?: Record<string, string>;
+}
+export interface CreateShardGroupResult {
+    groupId: string;
+    actorType: string;
+    shardActorIds: string[];
+    shardCount: number;
+}
+export interface ScatterGatherOptions {
+    groupId: string;
+    query: Record<string, unknown>;
+    aggregation?: 'concat' | 'merge' | 'first' | 'majority';
+    timeoutMs?: number;
+    minResponses?: number;
+}
+export interface ShardQueryResult {
+    shardId: number;
+    shardActorId: string;
+    payload: unknown;
+    success: boolean;
+    error: string;
+}
+export interface ScatterGatherResult {
+    shardResponses: ShardQueryResult[];
+}
+export interface BroadcastShardGroupOptions {
+    groupId: string;
+    message: Record<string, unknown>;
+    timeoutMs?: number;
+    minAcks?: number;
+}
+export interface ReduceShardGroupOptions {
+    groupId: string;
+    mapFunction: Record<string, unknown>;
+    reduction: 'sum' | 'min' | 'max' | 'product' | 'concat' | 'bool_and' | 'bool_or';
+    target?: string;
+    timeoutMs?: number;
+    minResponses?: number;
+}
+export type AllReduceShardGroupOptions = ReduceShardGroupOptions;
+export interface BarrierShardGroupOptions {
+    groupId: string;
+    barrierId: string;
+    round?: number;
+    timeoutMs?: number;
+    minAcks?: number;
+}
+export interface MapShardGroupOptions {
+    groupId: string;
+    mapFunction: Record<string, unknown>;
+    timeoutMs?: number;
+    minResponses?: number;
+}
+export interface BulkUpdateShardGroupOptions {
+    groupId: string;
+    updates: Record<string, Record<string, unknown>>;
+    consistencyLevel?: 'eventual' | 'strong' | 'sequential';
+    timeoutMs?: number;
+    waitForResponses?: boolean;
+}

package/dist/shard_types.js

@@ -0,0 +1,5 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Copyright (C) 2025 PlexSpaces Contributors
+//
+// Typed request/response types for shard group host operations.
+export {};

package/dist/wire/shard-group-proto-wire.d.ts

@@ -4,4 +4,16 @@ export declare function decodeCreateShardGroupResponse(data: Uint8Array): Record
 export declare function decodeScatterGatherResponse(data: Uint8Array): Record<string, unknown>;
 export declare function decodeApplicationMetrics(data: Uint8Array): Record<string, unknown>;
 export declare function decodeGetApplicationStatusResponse(data: Uint8Array): Record<string, unknown>;
+export declare function encodeBulkUpdateShardGroupRequest(req: Record<string, unknown>): Uint8Array;
+export declare function decodeBulkUpdateShardGroupResponse(data: Uint8Array): Record<string, unknown>;
+export declare function encodeBroadcastShardGroupRequest(req: Record<string, unknown>): Uint8Array;
+export declare function encodeReduceShardGroupRequest(req: Record<string, unknown>): Uint8Array;
+export declare function encodeAllReduceShardGroupRequest(req: Record<string, unknown>): Uint8Array;
+export declare function encodeBarrierShardGroupRequest(req: Record<string, unknown>): Uint8Array;
+export declare function encodeMapShardGroupRequest(req: Record<string, unknown>): Uint8Array;
+export declare function decodeBroadcastShardGroupResponse(data: Uint8Array): Record<string, unknown>;
+export declare function decodeReduceShardGroupResponse(data: Uint8Array): Record<string, unknown>;
+export declare function decodeAllReduceShardGroupResponse(data: Uint8Array): Record<string, unknown>;
+export declare function decodeBarrierShardGroupResponse(data: Uint8Array): Record<string, unknown>;
+export declare function decodeMapShardGroupResponse(data: Uint8Array): Record<string, unknown>;
 export declare function encodeApplicationMetrics(metrics: Record<string, unknown>): Uint8Array;