@vampgg/utils 1.0.0-beta.4 → 1.0.0-beta.6

package/README.md

@@ -19,7 +19,7 @@ vp run build         # regenerate schema then build (runs: bebopc build && vp pa
 
 ## Schema (`schema/`)
 
-Two bebop types define the wire format for all RPC in this framework.
+Two bebop types define the wire format for all RPC in this framework. The remaining files are entity components that apps import into their own schema.
 
 ### `Error` (struct — `schema/error.bop`)
 
@@ -50,6 +50,37 @@ The universal envelope for all RPC calls. Fields are optional (bebop message typ
 | `credential`    | `string` | Serialized credential for storage       |
 | `headers`       | `string` | HTTP-style metadata header string       |
 
+### Behavior trees (`schema/behavior.bop`)
+
+Entity components for `@vampgg/ecs` behavior trees. Import the file from your
+`entity.bop` (as `vamp init` does), then add `Brain` and `BehaviorTree` fields to
+`Entity`. `vamp generate` merges both of their deltas as last-write-wins, never
+as counters.
+
+| Type               | Fields                                                                                  | Role                                                      |
+| ------------------ | --------------------------------------------------------------------------------------- | --------------------------------------------------------- |
+| `BehaviorNodeKind` | `Selector`, `Sequence`, `Weighted`, `Condition`, `Task`, `Invert`, `Chance`, `Cooldown` | What a node does                                          |
+| `BehaviorNode`     | `kind`, `children`, `weight`, `leaf`, `args`                                            | One node; `children` are indices into `nodes`             |
+| `BehaviorTree`     | `nodes`                                                                                 | A flat tree whose root is `nodes[0]`, stored on an entity |
+| `Brain`            | `tree`, `readyAt`, `last`                                                               | An agent's tree id, cooldown expiry ticks, and last task  |
+
+`weight` is a `Chance` percentage or a `Cooldown` length in ticks. A `Weighted`
+node keeps its per-child weights in `args`. `leaf` is the app's `Condition` or
+`Task` enum value.
+
+### Vectors (`schema/vec.bop`)
+
+Spatial entity components. Import the file from your `entity.bop` (as `vamp init`
+does), then add `Vec2` or `Vec3` fields to `Entity`. `vamp generate` merges their
+deltas as counters, so a delta of `{ x: 0.5 }` adds `0.5` to `x`.
+
+| Type        | Fields        | Role                                 |
+| ----------- | ------------- | ------------------------------------ |
+| `Vec2`      | `x`, `y`      | A 2D vector, such as a position      |
+| `Vec2Delta` | `x`, `y`      | Signed `float32` offsets onto a Vec2 |
+| `Vec3`      | `x`, `y`, `z` | A 3D vector                          |
+| `Vec3Delta` | `x`, `y`, `z` | Signed `float32` offsets onto a Vec3 |
+
 ---
 
 ## Subpath Exports

package/dist/async-queue.d.mts

@@ -52,12 +52,12 @@ declare class AsyncQueue<T> implements AsyncIterableIterator<T> {
   /** Producer: terminate the stream as a clean completion. Idempotent. */
   close(): void;
   /** Producer: terminate the stream with an error thrown into the consumer. Idempotent. */
-  fail(error: unknown): void;
+  fail(cause: unknown): void;
   next(): Promise<IteratorResult<T>>;
   /** Consumer aborted early (break / return). Runs dispose and ends the stream. */
-  return(value?: unknown): Promise<IteratorResult<T>>;
+  return(value?: undefined): Promise<IteratorResult<T>>;
   /** Consumer threw. Propagate after dispose. */
-  throw(e?: unknown): Promise<IteratorResult<T>>;
+  throw(cause?: unknown): Promise<IteratorResult<T>>;
   [Symbol.asyncIterator](): AsyncIterableIterator<T>;
   private enqueue;
   private dequeue;

package/dist/async-queue.mjs

@@ -62,15 +62,15 @@ var AsyncQueue = class {
 		}
 	}
 	/** Producer: terminate the stream with an error thrown into the consumer. Idempotent. */
-	fail(error) {
+	fail(cause) {
 		if (this.closed || this.hasError) return;
 		this.hasError = true;
-		this.error = error;
+		this.error = cause;
 		if (this.pendingReject) {
 			const reject = this.pendingReject;
 			this.pendingResolve = null;
 			this.pendingReject = null;
-			reject(error);
+			reject(cause);
 		}
 	}
 	async next() {
@@ -113,16 +113,16 @@ var AsyncQueue = class {
 		};
 	}
 	/** Consumer threw. Propagate after dispose. */
-	async throw(e) {
+	async throw(cause) {
 		this.closed = true;
 		if (this.pendingReject) {
 			const reject = this.pendingReject;
 			this.pendingResolve = null;
 			this.pendingReject = null;
-			reject(e);
+			reject(cause);
 		}
 		await this.dispose();
-		throw e;
+		throw cause;
 	}
 	[Symbol.asyncIterator]() {
 		return this;

package/dist/channel-core.d.mts

@@ -28,7 +28,7 @@ declare abstract class CoreChannel extends BaseChannel {
    * Reject callbacks for in-flight unary / client-stream calls, keyed by
    * messageId. Lets close()/error() settle parked requests instead of hanging.
    */
-  readonly pending: Map<string, (e: unknown) => void>;
+  readonly pending: Map<string, (cause: unknown) => void>;
   protected closed: boolean;
   /** The reason a closed channel settles calls that arrive after teardown. */
   protected closeReason?: TempoError;
@@ -39,7 +39,7 @@ declare abstract class CoreChannel extends BaseChannel {
    * synchronous (worker / WebSocket) or asynchronous (extension runtime); the
    * call sites await or attach rejection handlers as each RPC shape requires.
    */
-  protected abstract sendFrame(message: Message): void | Promise<unknown>;
+  protected abstract sendFrame(message: Message): void | Promise<void>;
   /** Generates the unique id for an outgoing request envelope. */
   protected generateMessageId(): string;
   /**

package/dist/channel-core.mjs

@@ -308,14 +308,14 @@ var CoreChannel = class extends BaseChannel {
 	* Runs the shared error-hook + error-mapping tail of every `start*` method.
 	* Always throws.
 	*/
-	async raiseCallError(context, e) {
-		if (this.hooks !== void 0 && e instanceof Error) await this.hooks.executeErrorHooks(context, e);
-		if (e instanceof TempoError) throw e;
-		if (e instanceof Error) {
-			if (e.name === "AbortError") throw new TempoError(TempoStatusCode.ABORTED, "RPC fetch aborted", e);
-			throw new TempoError(TempoStatusCode.UNKNOWN, "an unknown error occurred", e);
+	async raiseCallError(context, cause) {
+		if (this.hooks !== void 0 && cause instanceof Error) await this.hooks.executeErrorHooks(context, cause);
+		if (cause instanceof TempoError) throw cause;
+		if (cause instanceof Error) {
+			if (cause.name === "AbortError") throw new TempoError(TempoStatusCode.ABORTED, "RPC fetch aborted", cause);
+			throw new TempoError(TempoStatusCode.UNKNOWN, "an unknown error occurred", cause);
 		}
-		throw new TempoError(TempoStatusCode.UNKNOWN, "an unknown error occurred", { data: e });
+		throw new TempoError(TempoStatusCode.UNKNOWN, "an unknown error occurred", { data: cause });
 	}
 	/**
 	* {@inheritDoc BaseChannel.startUnary}

package/dist/context-logger.d.mts

@@ -1,11 +1,13 @@
 import { ConsoleLogger, TempoLogLevel, TempoLogger } from "@tempojs/common";
 
 //#region src/context-logger.d.ts
+/** Structured log fields, as TempoLogger's own `write` contract defines them. */
+type LogData = NonNullable<Parameters<TempoLogger["write"]>[2]>;
 declare class ContextLogger extends ConsoleLogger {
-  bindings: Record<string, unknown>;
-  constructor(sourceName: string, logLevel?: TempoLogLevel, parent?: TempoLogger, bindings?: Record<string, unknown>);
-  correlate<TLogger extends TempoLogger>(sourceName: string, correlationId?: string, asOrphan?: boolean, bindings?: Record<string, unknown>): TLogger;
-  clone<TLogger extends TempoLogger>(sourceName: string, asOrphan?: boolean, bindings?: Record<string, unknown>): TLogger;
+  bindings: LogData;
+  constructor(sourceName: string, logLevel?: TempoLogLevel, parent?: TempoLogger, bindings?: LogData);
+  correlate<TLogger extends TempoLogger>(sourceName: string, correlationId?: string, asOrphan?: boolean, bindings?: LogData): TLogger;
+  clone<TLogger extends TempoLogger>(sourceName: string, asOrphan?: boolean, bindings?: LogData): TLogger;
 }
 //#endregion
-export { ContextLogger };
+export { ContextLogger, LogData };

package/dist/context-logger.mjs

@@ -8,10 +8,9 @@ var ContextLogger = class extends ConsoleLogger {
 		TempoLogger.instances.delete(sourceName.replace(/\s+/g, "_"));
 	}
 	correlate(sourceName, correlationId, asOrphan, bindings) {
-		return this.clone(sourceName, asOrphan, {
-			...correlationId ? { correlationId } : {},
-			...bindings
-		});
+		const merged = correlationId ? { correlationId } : {};
+		Object.assign(merged, bindings);
+		return this.clone(sourceName, asOrphan, merged);
 	}
 	clone(sourceName, asOrphan, bindings) {
 		const logger = Reflect.construct(this.constructor, [

package/dist/create-event-iterator.d.mts

@@ -4,7 +4,7 @@ import { AsyncQueue, AsyncQueueOptions } from "./async-queue.mjs";
 type Context<T> = {
   emit: (value: T) => void; /** Terminate the stream as a clean completion. */
   cancel: () => void; /** Terminate the stream with an error thrown into the consumer's `for await`. */
-  error: (e: unknown) => void;
+  error: (cause: unknown) => void;
 };
 type CleanupFn = () => void | Promise<void>;
 type Subscriber<T> = (context: Context<T>) => void | CleanupFn | Promise<CleanupFn | void>;

package/dist/create-event-iterator.mjs

@@ -34,9 +34,9 @@ function queueIterator(queue, start) {
 			if (started !== void 0) await started.catch(() => {});
 			return queue.return(value);
 		},
-		async throw(e) {
+		async throw(cause) {
 			if (started !== void 0) await started.catch(() => {});
-			return queue.throw(e);
+			return queue.throw(cause);
 		},
 		[Symbol.asyncIterator]() {
 			return this;
@@ -57,7 +57,7 @@ function createEventIterator(subscriber, options) {
 			queue.push(value);
 		},
 		cancel: () => queue.close(),
-		error: (e) => queue.fail(e)
+		error: (cause) => queue.fail(cause)
 	};
 	return queueIterator(queue, async () => {
 		unsubscribe = await subscriber(context);

package/dist/extension-channel.d.mts

@@ -33,8 +33,8 @@ declare class TempoExtensionChannel extends CoreChannel {
   /**
    * {@inheritDoc CoreChannel.sendFrame}
    */
-  protected sendFrame(message: Message): Promise<unknown>;
-  protected sendMessage(message: Message): Promise<unknown>;
+  protected sendFrame(message: Message): Promise<void>;
+  protected sendMessage(message: Message): Promise<void>;
 }
 //#endregion
 export { TempoExtensionChannel };

package/dist/extension-router.d.mts

@@ -159,6 +159,6 @@ type ExtensionSenderContext = {
  * ignored. Replies travel back through the router's send path, so this never
  * uses `sendResponse`.
  */
-declare function createExtensionListener(router: Pick<TempoExtensionRouter<ExtensionSenderContext>, "process">, registry: ServiceRegistry): (raw: unknown, sender: Runtime.MessageSender) => undefined;
+declare function createExtensionListener(router: Pick<TempoExtensionRouter<ExtensionSenderContext>, "process">, registry: ServiceRegistry): Runtime.OnMessageListenerNoResponse;
 //#endregion
 export { ExtensionBaseRouter, ExtensionSenderContext, TempoExtensionRouter, TempoExtensionRouterConfiguration, createExtensionListener };

package/dist/pino-logger.d.mts

@@ -1,4 +1,4 @@
-import { ContextLogger } from "./context-logger.mjs";
+import { ContextLogger, LogData } from "./context-logger.mjs";
 import { ConsoleLogger, TempoLogLevel, TempoLogger } from "@tempojs/common";
 import pino from "pino";
 
@@ -8,34 +8,34 @@ declare class PinoLogger extends ContextLogger implements ConsoleLogger {
   sourceName: string;
   logLevel: TempoLogLevel;
   children: Set<TempoLogger>;
-  constructor(sourceName: string, logLevel?: TempoLogLevel, parent?: pino.Logger, bindings?: Record<string, unknown>);
+  constructor(sourceName: string, logLevel?: TempoLogLevel, parent?: pino.Logger, bindings?: LogData);
   static getPinoLevel(level: string): string;
-  clone<TLogger extends TempoLogger>(sourceName: string, asOrphan?: boolean, bindings?: Record<string, unknown>): TLogger;
-  write(level: TempoLogLevel, message: string, data?: Record<string, unknown>, error?: Error): void;
+  clone<TLogger extends TempoLogger>(sourceName: string, asOrphan?: boolean, bindings?: LogData): TLogger;
+  write(level: TempoLogLevel, message: string, data?: LogData, error?: Error): void;
   /**
    * @inheritDoc
    */
-  trace(message: string, data?: Record<string, unknown>, error?: Error): void;
+  trace(message: string, data?: LogData, error?: Error): void;
   /**
    * @inheritDoc
    */
-  debug(message: string, data?: Record<string, unknown>, error?: Error): void;
+  debug(message: string, data?: LogData, error?: Error): void;
   /**
    * @inheritDoc
    */
-  info(message: string, data?: Record<string, unknown>, error?: Error): void;
+  info(message: string, data?: LogData, error?: Error): void;
   /**
    * @inheritDoc
    */
-  warn(message: string, data?: Record<string, unknown>, error?: Error): void;
+  warn(message: string, data?: LogData, error?: Error): void;
   /**
    * @inheritDoc
    */
-  error(message: string, data?: Record<string, unknown>, error?: Error): void;
+  error(message: string, data?: LogData, error?: Error): void;
   /**
    * @inheritDoc
    */
-  critical(message: string, data?: Record<string, unknown>, error?: Error): void;
+  critical(message: string, data?: LogData, error?: Error): void;
   setLogLevel(level: TempoLogLevel): void;
   private tempoPinoLevelMap;
   formatErrorMessage(error: Error, indentLevel?: number): string;

package/dist/router-core.d.mts

@@ -115,7 +115,7 @@ declare class RouterCore {
    * type, populate and deliver the response, and map any failure onto an error
    * frame. Transport-specific behavior is injected via `transport`.
    */
-  processRequest(request: Message, response: Message, env: unknown, transport: ProcessTransport, contentType?: BebopContentType): Promise<void>;
+  processRequest<TEnv>(request: Message, response: Message, env: TEnv, transport: ProcessTransport, contentType?: BebopContentType): Promise<void>;
 }
 //#endregion
 export { ProcessTransport, RouterCore, RouterCoreHost, StreamWriteOptions };

package/dist/service-registry.d.mts

@@ -0,0 +1,21 @@
+import { TempoLogger } from "@tempojs/common";
+import { BebopMethodAny, ServiceRegistry } from "@tempojs/server";
+
+//#region src/service-registry.d.ts
+/**
+ * One router takes one registry, but a host can generate services across
+ * several packages (each with its own registry class). Method ids are
+ * service+method hashes (collision-free across services), so first-hit-wins
+ * lookup is safe. Generated `init()` is destructive (moves the
+ * decorator-registered singleton out of a static map), so it must run exactly
+ * once — the router constructor also calls `init()`.
+ */
+declare class CompositeServiceRegistry extends ServiceRegistry {
+  #private;
+  private readonly registries;
+  constructor(logger: TempoLogger, registries: readonly ServiceRegistry[]);
+  init(): void;
+  getMethod(methodId: number): BebopMethodAny | undefined;
+}
+//#endregion
+export { CompositeServiceRegistry };

package/dist/service-registry.mjs

@@ -0,0 +1,31 @@
+import { ServiceRegistry } from "@tempojs/server";
+//#region src/service-registry.ts
+/**
+* One router takes one registry, but a host can generate services across
+* several packages (each with its own registry class). Method ids are
+* service+method hashes (collision-free across services), so first-hit-wins
+* lookup is safe. Generated `init()` is destructive (moves the
+* decorator-registered singleton out of a static map), so it must run exactly
+* once — the router constructor also calls `init()`.
+*/
+var CompositeServiceRegistry = class extends ServiceRegistry {
+	registries;
+	#initialized = false;
+	constructor(logger, registries) {
+		super(logger);
+		this.registries = registries;
+	}
+	init() {
+		if (this.#initialized) return;
+		this.#initialized = true;
+		for (const registry of this.registries) registry.init();
+	}
+	getMethod(methodId) {
+		for (const registry of this.registries) {
+			const method = registry.getMethod(methodId);
+			if (method) return method;
+		}
+	}
+};
+//#endregion
+export { CompositeServiceRegistry };

package/dist/ws-channel.mjs

@@ -79,7 +79,7 @@ var TempoWSChannel = class TempoWSChannel extends CoreChannel {
 	*/
 	static forAddress(address, options) {
 		if (!address) throw new Error("no address");
-		if (typeof address === "string") address = new URL(address);
+		if (!(address instanceof URL)) address = new URL(address);
 		options ??= {};
 		return new TempoWSChannel(address, options);
 	}
@@ -102,14 +102,15 @@ var TempoWSChannel = class TempoWSChannel extends CoreChannel {
 			this.close(new TempoError(TempoStatusCode.UNAVAILABLE, "channel transport error"));
 		});
 		this.ws.addEventListener(WebsocketEvent.message, (_ws, ev) => {
-			const byteLength = typeof ev.data === "string" ? ev.data.length : ev.data.byteLength;
+			const data = ev.data;
+			const byteLength = data instanceof ArrayBuffer ? data.byteLength : data.length;
 			if (byteLength > this.maxReceiveMessageSize) {
 				this.logger.error(`inbound frame ${byteLength}B exceeds maxReceiveMessageSize ${this.maxReceiveMessageSize}B; dropping`);
 				return;
 			}
 			let message;
-			if (typeof ev.data === "string") message = Message(JSON.parse(ev.data));
-			else message = Message(Message.decode(new Uint8Array(ev.data)));
+			if (data instanceof ArrayBuffer) message = Message(Message.decode(new Uint8Array(data)));
+			else message = Message(JSON.parse(data));
 			const messageId = message.messageId;
 			this.events.emit(messageId, message);
 			this.logger.trace(`received new message ${messageId}`);
@@ -168,8 +169,7 @@ var TempoWSChannel = class TempoWSChannel extends CoreChannel {
 					};
 					const onError = (ws, event) => {
 						teardown();
-						const message = event.message;
-						const detail = typeof message === "string" ? message : event.type;
+						const detail = event.message ?? event.type;
 						reject(new TempoError(TempoStatusCode.UNAVAILABLE, `socket error before open: ${detail}`));
 					};
 					const onClose = () => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vampgg/utils",
-  "version": "1.0.0-beta.4",
+  "version": "1.0.0-beta.6",
   "description": "Tempo RPC, Bebop serialization, transports, and async primitives for @vampgg.",
   "homepage": "https://github.com/sammccord/vamp/tree/main/packages/utils#readme",
   "bugs": {
@@ -29,6 +29,7 @@
     "./extension-router": "./dist/extension-router.mjs",
     "./pino-logger": "./dist/pino-logger.mjs",
     "./router-core": "./dist/router-core.mjs",
+    "./service-registry": "./dist/service-registry.mjs",
     "./worker-channel": "./dist/worker-channel.mjs",
     "./worker-router": "./dist/worker-router.mjs",
     "./ws-channel": "./dist/ws-channel.mjs",

package/schema/behavior.bop

@@ -0,0 +1,45 @@
+// Behavior tree built-ins. A BehaviorTree lives on its own entity and is shared
+// by every agent whose Brain points at it. Nodes form a flat array linked by
+// index; nodes[0] is the root.
+enum BehaviorNodeKind {
+  Selector = 1;   // first child that succeeds
+  Sequence = 2;   // every child succeeds, in order
+  Weighted = 3;   // children that pass, picked by weight
+  Condition = 4;  // leaf: registered predicate
+  Task = 5;       // leaf: registered task, emits action intents
+  Invert = 6;
+  Chance = 7;     // decorator: passes with probability weight/100
+  Cooldown = 8;   // decorator: fails until `weight` ticks since its last success
+}
+
+message BehaviorNode {
+  1 -> BehaviorNodeKind kind;
+  2 -> uint16[] children;   // indices into BehaviorTree.nodes
+  3 -> uint32 weight;       // Chance percent or Cooldown ticks
+  4 -> uint32 leaf;         // Condition / Task id (app enum)
+  5 -> float32[] args;      // leaf arguments; per-child weights on Weighted
+}
+
+message BehaviorTree {
+  1 -> BehaviorNode[] nodes;
+}
+
+// Behavior tree delta - last-write-wins replace of the whole node array
+message BehaviorTreeDelta {
+  1 -> BehaviorNode[] nodes;
+}
+
+message Brain {
+  1 -> string tree;         // id of the entity that holds the BehaviorTree
+  2 -> uint32[] readyAt;    // per-node cooldown expiry tick
+  3 -> uint16 last;         // last task node that fired
+  4 -> uint32 fingerprint;  // of the tree that readyAt and last index into
+}
+
+// Brain delta - every field is last-write-wins
+message BrainDelta {
+  1 -> string tree;
+  2 -> uint32[] readyAt;
+  3 -> uint16 last;
+  4 -> uint32 fingerprint;
+}

package/schema/pool.bop

@@ -3,7 +3,7 @@ message Pool {
 	2 -> uint32 min;
 	3 -> uint32 max;
 	4 -> int32 rate;
-  5 -> uint32 interval;
+    5 -> uint32 interval;
 }
 
 // Pool delta - points is CRDT counter, others are last-write-wins

package/schema/vec.bop

@@ -0,0 +1,24 @@
+// Vector built-ins for positions, velocities, and other spatial components.
+message Vec2 {
+  1 -> float32 x;
+  2 -> float32 y;
+}
+
+// Vec2 delta - every field is a float CRDT counter (+/-)
+message Vec2Delta {
+  1 -> float32 x;
+  2 -> float32 y;
+}
+
+message Vec3 {
+  1 -> float32 x;
+  2 -> float32 y;
+  3 -> float32 z;
+}
+
+// Vec3 delta - every field is a float CRDT counter (+/-)
+message Vec3Delta {
+  1 -> float32 x;
+  2 -> float32 y;
+  3 -> float32 z;
+}