posipaki 0.37.0 → 0.38.0

package/dist/define-actor-CCJy7LDp.js

@@ -0,0 +1,189 @@
+import { a as spawnAsync, i as runDispatchAsync } from "./process.async-CdQ_zpKp.js";
+import { a as STOP_SENTINEL, i as PROPAGATE_SENTINEL, t as callHook } from "./hooks-CgXhmY4r.js";
+//#region src/define-actor.ts
+function defineMessages() {}
+function hidePrivate(value) {
+	if (value && typeof value === "object" && "private" in value && "public" in value) return value.public;
+	return value;
+}
+function resolvePlugins(raw, parentPlugins, addPlugins) {
+	const resolved = !raw ? parentPlugins ? [...parentPlugins] : [] : Array.isArray(raw) ? [...raw] : raw(parentPlugins ?? []);
+	const combined = addPlugins ? [...resolved, ...addPlugins] : resolved;
+	const seen = /* @__PURE__ */ new Set();
+	return combined.filter((p) => {
+		const name = p.name;
+		if (!name) {
+			console.warn("posipaki: plugin has no name, dedup won't work");
+			return true;
+		}
+		if (seen.has(name)) return false;
+		seen.add(name);
+		return true;
+	});
+}
+async function assembleActor(config, plugins, addPlugins) {
+	let cur = config;
+	for (const p of plugins) try {
+		cur = await p(cur);
+	} catch (e) {
+		console.error(`[assembleActor] plugin "${p.name || "?"}" failed:`, e);
+	}
+	cur.resolvedPlugins = plugins;
+	if (addPlugins) cur.addPlugins = addPlugins;
+	return cur;
+}
+function defineActor(config) {
+	const actorCtxMap = /* @__PURE__ */ new Map();
+	function makeRuntime(assembly) {
+		return async function* (ctx, args) {
+			let done = false;
+			let exitReason;
+			let rawState = void 0;
+			const decorated = /* @__PURE__ */ new Map();
+			const self = {
+				ctx,
+				...assembly.methods || {},
+				...assembly.$decorate || {},
+				reflection: {},
+				state: rawState,
+				name: ctx.pname,
+				id: ctx.id,
+				async emit(msg) {
+					await callHook(assembly.onEmit, void 0, self, msg, {
+						fromName: ctx.pname,
+						fromId: ctx.id
+					});
+					ctx.toParent(msg);
+				},
+				agreeToStop() {
+					exitReason = "stopped";
+					done = true;
+				},
+				exit(reason) {
+					exitReason = reason;
+					done = true;
+					ctx.wake();
+				},
+				$child: {},
+				decorators: {},
+				fork: async (childActor, childArgs, forkOpts) => {
+					let child;
+					const childName = forkOpts?.name ?? childActor?.name ?? `child-${Object.keys(self.$child).length}`;
+					const treeName = `${ctx.pname}:${childName}`;
+					const childAddPlugins = [...assembly.addPlugins || [], ...forkOpts?.addPlugins || []];
+					child = await childActor.spawnAsChild(ctx, childArgs, {
+						name: treeName,
+						parentPlugins: assembly.resolvedPlugins || [],
+						...childAddPlugins.length ? { addPlugins: childAddPlugins } : {}
+					});
+					self.$child[child.pname] = child;
+					return child;
+				}
+			};
+			actorCtxMap.set(ctx.id, self);
+			/**
+			* Lifecycle hooks are the actor's own control flow: if one throws, the
+			* state machine is half-applied, so the error is fatal — `onError` still
+			* observes it (a logger logs it), but it cannot absorb it.  The actor goes
+			* down and its parent still gets the EXIT, instead of staying up with
+			* nothing left to do.
+			*
+			* Message hooks and handlers are not forced either way: they are called
+			* with `onError` itself, and its *return value* decides — nothing means
+			* "handled, carry on" (the default, and what an observing logger
+			* returns), `propagateError()` means "not handled", and the actor goes
+			* down with the same EXIT.
+			*/
+			const hookErrorHandler = async (e) => {
+				try {
+					await assembly.onError?.call(self, e);
+				} catch {}
+				return PROPAGATE_SENTINEL;
+			};
+			ctx.afterExit = async () => {
+				await callHook(assembly.afterEnd, hookErrorHandler, self, exitReason);
+			};
+			for (const [k, v] of decorated) self[k] = v;
+			await callHook(assembly.beforeStart, hookErrorHandler, self);
+			if (assembly.setup) rawState = await assembly.setup.call(self, args);
+			else rawState = null;
+			self.state = rawState;
+			yield hidePrivate(rawState);
+			await callHook(assembly.afterStart, hookErrorHandler, self);
+			yield* runDispatchAsync(ctx.pname, async (stamped) => {
+				const [msg, sender] = stamped;
+				if (msg.type === "__ADVANCE__") return;
+				if (msg.type === "STOP") {
+					if (assembly.onStopRequested) await callHook(assembly.onStopRequested, hookErrorHandler, self);
+					else {
+						exitReason = "stopped";
+						done = true;
+					}
+					return;
+				}
+				if (msg.type === "EXIT") {
+					const childName = sender.fromName;
+					if (childName && self.$child[childName]) delete self.$child[childName];
+					await callHook(assembly.onChildExit, hookErrorHandler, self, childName, msg);
+					const orphans = msg.orphans;
+					if (orphans && orphans.length > 0) for (const orphan of orphans) {
+						const decision = assembly.onOrphan ? await callHook(assembly.onOrphan, hookErrorHandler, self, orphan) : "force-stop";
+						if (decision === "adopt") {
+							ctx.adopt(orphan);
+							const idx = ctx.orphans.indexOf(orphan);
+							if (idx >= 0) ctx.orphans.splice(idx, 1);
+							self.$child[orphan.pname] = orphan;
+						} else if (decision === "force-stop") {
+							orphan.forceStop({ cascade: true });
+							const idx = ctx.orphans.indexOf(orphan);
+							if (idx >= 0) ctx.orphans.splice(idx, 1);
+						} else if (decision === "unparent") orphan.unparent();
+					}
+				}
+				let hookStopped = false;
+				if (msg.type !== "STOP" && msg.type !== "EXIT" && assembly.onMessage) {
+					if (await callHook(assembly.onMessage, assembly.onError, self, msg, sender) === STOP_SENTINEL) hookStopped = true;
+				}
+				if (msg.type !== "STOP" && !hookStopped) {
+					const handler = (assembly.handlers || {})[msg.type] || assembly.onUnhandled;
+					await callHook(handler, assembly.onError, self, msg, sender);
+				}
+			}, () => done);
+			await callHook(assembly.beforeEnd, hookErrorHandler, self, exitReason);
+		};
+	}
+	function attachReflection(proc, reflectionMethods) {
+		const self = actorCtxMap.get(proc.id);
+		if (self) proc.$reflection = self.reflection;
+		if (!reflectionMethods) return;
+		const refl = proc.$reflection;
+		const written = Object.entries(reflectionMethods);
+		for (const [k, m] of written) refl[k] = async (...args) => await m.apply(self, args);
+	}
+	return {
+		fn: makeRuntime(config),
+		name: config.name,
+		pvtPluginsRaw: config.plugins,
+		inMessages: config.inMessages,
+		outMessages: config.outMessages,
+		async spawn(args, opts) {
+			const assembly = await assembleActor(config, resolvePlugins(config.plugins, void 0, opts?.addPlugins), opts?.addPlugins);
+			const runtime = makeRuntime(assembly);
+			const proc = spawnAsync(runtime, opts?.name ?? assembly.name ?? "actor", opts?.toParent, opts?.parentName, opts?.parentId)(args);
+			attachReflection(proc, assembly.$reflectionMethods);
+			if (opts?.awaitReady !== false) await proc.ready();
+			return proc;
+		},
+		async spawnAsChild(ctx, args, opts) {
+			const assembly = await assembleActor(config, resolvePlugins(config.plugins, opts?.parentPlugins, opts?.addPlugins), opts?.addPlugins);
+			const runtime = makeRuntime(assembly);
+			const proc = ctx.fork(runtime, opts?.name ?? assembly.name ?? "child")(args);
+			attachReflection(proc, assembly.$reflectionMethods);
+			return proc;
+		}
+	};
+}
+//#endregion
+export { defineMessages as n, defineActor as t };
+
+//# sourceMappingURL=define-actor-CCJy7LDp.js.map

package/dist/define-actor-CCJy7LDp.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"define-actor-CCJy7LDp.js","names":[],"sources":["../src/define-actor.ts"],"sourcesContent":["// ── defineActor — high-level actor wrapper ───────────────────────────────────\n//\n// Compiles a declarative config into an AsyncProcessFn.  Built on top of\n// the existing runDispatchAsync / spawnAsync primitives.\n//\nimport {\n  type AsyncProcess,\n  runDispatchAsync,\n  spawnAsync,\n  AnyProcess,\n  INTERNAL_ADVANCE,\n} from \"./process.async.js\";\nimport type {\n  WithSender,\n  SenderInfo,\n  AsyncProcessFn,\n  Message,\n  ExitMessage,\n  ProcessCtx,\n} from \"./types.js\";\nimport type {\n  ActorDefinition,\n  ActorConfig,\n  ActorContext,\n  MethodOptions,\n  ActorMessages,\n  HandlerOptions,\n  HandlerFn,\n  ReflectionOptions,\n  AnyConfig,\n  HidePrivate,\n} from \"./actor-types.js\";\nimport { STOP_SENTINEL, PROPAGATE_SENTINEL } from \"./actor-types.js\";\nimport { ActorDecorated, type ActorPlugin, ActorReflection, callHook } from \"./hooks.js\";\n\nexport function defineMessages<OutMsg extends Message = Message>(): ActorMessages<OutMsg> {\n  return undefined as unknown as ActorMessages<OutMsg>;\n}\n\nfunction hidePrivate<T>(value: T): HidePrivate<T> {\n  if (value && typeof value === \"object\" && \"private\" in value && \"public\" in value) {\n    return value.public as HidePrivate<T>;\n  }\n  return value as HidePrivate<T>;\n}\n\nfunction resolvePlugins(\n  raw: ActorPlugin[] | ((parents: ActorPlugin[]) => ActorPlugin[]) | undefined,\n  parentPlugins?: ActorPlugin[],\n  addPlugins?: ActorPlugin[],\n): ActorPlugin[] {\n  const resolved = !raw\n    ? parentPlugins\n      ? [...parentPlugins]\n      : []\n    : Array.isArray(raw)\n      ? [...raw]\n      : raw(parentPlugins ?? []);\n\n  const combined = addPlugins ? [...resolved, ...addPlugins] : resolved;\n\n  // Deduplicate by function name\n  const seen = new Set<string>();\n  return combined.filter((p) => {\n    const name = p.name;\n    if (!name) {\n      console.warn(\"posipaki: plugin has no name, dedup won't work\");\n      return true;\n    }\n    if (seen.has(name)) return false;\n    seen.add(name);\n    return true;\n  });\n}\n\nasync function assembleActor<C>(\n  config: C,\n  plugins: ActorPlugin[],\n  addPlugins?: ActorPlugin[],\n): Promise<C> {\n  // Work with the default ActorPlugin type internally, cast back on return\n  let cur = config as AnyConfig;\n  for (const p of plugins) {\n    try {\n      cur = await p(cur);\n    } catch (e: unknown) {\n      console.error(`[assembleActor] plugin \"${p.name || \"?\"}\" failed:`, e);\n    }\n  }\n  cur.resolvedPlugins = plugins;\n  if (addPlugins) cur.addPlugins = addPlugins;\n  return cur as C;\n}\n\nexport function defineActor<\n  Args,\n  InternalState,\n  InMsg extends Message,\n  OutMsg extends Message,\n  Methods extends MethodOptions,\n  Handlers extends HandlerOptions<InMsg>,\n  ReflectionMethods extends ReflectionOptions,\n>(\n  config: ActorConfig<Args, InternalState, InMsg, OutMsg, Methods, Handlers, ReflectionMethods>,\n): ActorDefinition<Args, InternalState, InMsg, OutMsg, ReflectionMethods> {\n  const actorCtxMap = new Map<\n    symbol,\n    ActorContext<Args, InternalState, InMsg, OutMsg, Methods, Handlers, ReflectionMethods>\n  >();\n\n  function makeRuntime(\n    assembly: ActorConfig<Args, InternalState, InMsg, OutMsg, Methods, Handlers, ReflectionMethods>,\n  ): AsyncProcessFn<Args, HidePrivate<InternalState>, InMsg, OutMsg> {\n    return async function* (\n      ctx,\n      args,\n    ): AsyncGenerator<HidePrivate<InternalState | null>, void, WithSender<InMsg>> {\n      let done = false;\n      let exitReason: unknown;\n      let rawState: InternalState = undefined as unknown as InternalState;\n\n      const decorated = new Map();\n      const self: ActorContext<\n        Args,\n        InternalState,\n        InMsg,\n        OutMsg,\n        Methods,\n        Handlers,\n        ReflectionMethods & ActorReflection\n      > = {\n        ctx,\n        ...((assembly.methods || {}) as Methods),\n        ...((assembly.$decorate || {}) as ActorDecorated),\n        reflection: {} as ReflectionMethods & ActorReflection,\n        state: rawState,\n        name: ctx.pname,\n        id: ctx.id,\n        async emit(msg: OutMsg) {\n          await callHook(assembly.onEmit, undefined, self, msg, {\n            fromName: ctx.pname,\n            fromId: ctx.id,\n          });\n          ctx.toParent(msg);\n        },\n        agreeToStop() {\n          exitReason = \"stopped\";\n          done = true;\n        },\n        exit(reason: unknown) {\n          exitReason = reason;\n          done = true;\n          // The loop only re-reads `done` when it is resumed: an idle actor is\n          // parked at its dispatch yield and would sit there forever.\n          ctx.wake();\n        },\n        $child: {} as Record<string, AnyProcess>,\n        decorators: {},\n        fork: async <A, S, IM extends Message, OM extends InMsg, R extends ReflectionOptions>(\n          childActor: ActorDefinition<A, S, IM, OM, R>,\n          childArgs?: A,\n          forkOpts?: { name?: string; addPlugins?: ActorPlugin[] },\n        ): Promise<AsyncProcess<A, HidePrivate<S>, IM, OM, R & ActorReflection>> => {\n          let child: AsyncProcess<A, HidePrivate<S>, IM, OM, R & ActorReflection>;\n          const childName =\n            forkOpts?.name ?? childActor?.name ?? `child-${Object.keys(self.$child).length}`;\n          const treeName = `${ctx.pname}:${childName}`;\n          const childAddPlugins = [...(assembly.addPlugins || []), ...(forkOpts?.addPlugins || [])];\n          child = await childActor.spawnAsChild(ctx, childArgs!, {\n            name: treeName,\n            parentPlugins: assembly.resolvedPlugins || [],\n            ...(childAddPlugins.length ? { addPlugins: childAddPlugins } : {}),\n          });\n          self.$child[child.pname] = child as unknown as AnyProcess;\n          return child;\n        },\n      };\n      actorCtxMap.set(ctx.id, self);\n      /**\n       * Lifecycle hooks are the actor's own control flow: if one throws, the\n       * state machine is half-applied, so the error is fatal — `onError` still\n       * observes it (a logger logs it), but it cannot absorb it.  The actor goes\n       * down and its parent still gets the EXIT, instead of staying up with\n       * nothing left to do.\n       *\n       * Message hooks and handlers are not forced either way: they are called\n       * with `onError` itself, and its *return value* decides — nothing means\n       * \"handled, carry on\" (the default, and what an observing logger\n       * returns), `propagateError()` means \"not handled\", and the actor goes\n       * down with the same EXIT.\n       */\n      const hookErrorHandler = async (e: unknown): Promise<unknown> => {\n        try {\n          await assembly.onError?.call(self, e);\n        } catch {\n          // An error in the error handler must not mask the original one.\n        }\n        return PROPAGATE_SENTINEL;\n      };\n      ctx.afterExit = async () => {\n        await callHook(assembly.afterEnd, hookErrorHandler, self, exitReason);\n      };\n\n      for (const [k, v] of decorated) {\n        (self as Record<string, unknown>)[k] = v;\n      }\n\n      await callHook(\n        assembly.beforeStart,\n        hookErrorHandler,\n        self as ActorContext<\n          Args,\n          never, // state not set yet\n          InMsg,\n          OutMsg,\n          Methods,\n          Handlers,\n          ReflectionMethods & ActorReflection\n        >,\n      );\n\n      if (assembly.setup) {\n        rawState = await assembly.setup.call(\n          self as ActorContext<\n            Args,\n            never, // break inference cycle here\n            InMsg,\n            OutMsg,\n            Methods,\n            Handlers,\n            ReflectionMethods & ActorReflection\n          >,\n          args,\n        );\n      } else {\n        rawState = null as InternalState;\n      }\n      self.state = rawState;\n      yield hidePrivate(rawState);\n      await callHook(assembly.afterStart, hookErrorHandler, self);\n\n      yield* runDispatchAsync<WithSender<InMsg | ExitMessage>>(\n        ctx.pname,\n        async (stamped) => {\n          const [msg, sender] = stamped;\n          if (msg.type === INTERNAL_ADVANCE) return; // framework traffic, not a message\n          if (msg.type === \"STOP\") {\n            if (assembly.onStopRequested) {\n              await callHook(assembly.onStopRequested, hookErrorHandler, self);\n              // Hook may call agreeToStop(). If not, actor keeps running.\n            } else {\n              exitReason = \"stopped\";\n              done = true;\n            }\n            return;\n          }\n          if (msg.type === \"EXIT\") {\n            // FIXME: process name are user-specified\n            // and should not be used for indexing so\n            // we don't get into name conflicts\n            const childName = sender.fromName;\n            if (childName && self.$child[childName]) {\n              delete self.$child[childName];\n            }\n            await callHook(\n              assembly.onChildExit,\n              hookErrorHandler,\n              self,\n              childName,\n              msg as ExitMessage,\n            );\n            // Orphan policy: a child that exits may leave still-running\n            // grandchildren behind (see ctx-orphans / orphan-policy).\n            const orphans = (msg as ExitMessage).orphans;\n            if (orphans && orphans.length > 0) {\n              for (const orphan of orphans) {\n                // Default when no hook is defined: hard-kill the orphan.\n                const decision = assembly.onOrphan\n                  ? await callHook(assembly.onOrphan, hookErrorHandler, self, orphan)\n                  : \"force-stop\";\n                if (decision === \"adopt\") {\n                  ctx.adopt(orphan);\n                  const idx = ctx.orphans.indexOf(orphan);\n                  if (idx >= 0) ctx.orphans.splice(idx, 1);\n                  self.$child[orphan.pname] = orphan;\n                } else if (decision === \"force-stop\") {\n                  orphan.forceStop({ cascade: true });\n                  const idx = ctx.orphans.indexOf(orphan);\n                  if (idx >= 0) ctx.orphans.splice(idx, 1);\n                } else if (decision === \"unparent\") {\n                  orphan.unparent();\n                }\n                // 'leave' (or undefined) → do nothing; it propagates on exit.\n              }\n            }\n          }\n          let hookStopped = false;\n          if (msg.type !== \"STOP\" && msg.type !== \"EXIT\" && assembly.onMessage) {\n            const result = await callHook(\n              assembly.onMessage,\n              assembly.onError,\n              self,\n              msg as InMsg,\n              sender,\n            );\n            if (result === STOP_SENTINEL) hookStopped = true;\n          }\n          if (msg.type !== \"STOP\" && !hookStopped) {\n            const handler =\n              ((assembly.handlers || ({} as Handlers))[\n                msg.type as keyof Handlers\n              ] as HandlerFn<InMsg>) || assembly.onUnhandled;\n\n            await callHook(handler, assembly.onError, self, msg as InMsg, sender);\n          }\n        },\n        () => done,\n      );\n\n      await callHook(assembly.beforeEnd, hookErrorHandler, self, exitReason);\n    };\n  }\n\n  type ReflectableProcess = {\n    id: symbol;\n    $reflection: Record<string, Function>;\n  };\n  function attachReflection(\n    proc: ReflectableProcess,\n    reflectionMethods: ReflectionMethods | undefined,\n  ): void {\n    const self = actorCtxMap.get(proc.id);\n    if (self) {\n      // One object under two names: the surface the handle exposes as\n      // `$reflection` and the one the actor's own hooks see as `reflection`.\n      // Handing the same object to both is what lets a method be added after\n      // assembly — the first caller that needs that is a remote peer saying\n      // which methods it can answer.\n      proc.$reflection = self.reflection as unknown as Record<string, Function>;\n    }\n    if (!reflectionMethods) return;\n    const refl = proc.$reflection as Record<string, Function>;\n    // The declared contract is `ReflectionMethod`, whose parameters are `never`\n    // because nothing is called through it; this is the one place that calls\n    // what it describes.\n    const written = Object.entries(reflectionMethods) as Array<\n      [string, (...args: unknown[]) => unknown]\n    >;\n    for (const [k, m] of written) {\n      // A promise whatever the method was written as, so a caller reads the same\n      // call the same way whether the actor is here or behind a wire.\n      refl[k] = async (...args: unknown[]) => await m.apply(self, args);\n    }\n  }\n\n  return {\n    fn: makeRuntime(config),\n    name: config.name,\n    pvtPluginsRaw: config.plugins,\n    inMessages: config.inMessages,\n    outMessages: config.outMessages,\n    async spawn(\n      args: Args,\n      opts?: {\n        name?: string;\n        toParent?: (msg: OutMsg, from: SenderInfo) => void;\n        addPlugins?: ActorPlugin[];\n        parentName?: string | null;\n        parentId?: symbol | null;\n        /**\n         * Resolve only once the initial state is available.  Default `true`:\n         * a spawned process is safe to send to when `spawn()` returns.  Pass\n         * `false` for the raw handle — the caller then has to `await\n         * proc.ready()` itself before sending anything it wants handled.\n         */\n        awaitReady?: boolean;\n      },\n    ): Promise<\n      AsyncProcess<\n        Args,\n        HidePrivate<InternalState>,\n        InMsg,\n        OutMsg,\n        ReflectionMethods & ActorReflection\n      >\n    > {\n      const plugs = resolvePlugins(config.plugins, undefined, opts?.addPlugins);\n      const assembly = await assembleActor(config, plugs, opts?.addPlugins);\n      const runtime = makeRuntime(assembly);\n      const proc = spawnAsync(\n        runtime,\n        opts?.name ?? assembly.name ?? \"actor\",\n        opts?.toParent,\n        opts?.parentName,\n        opts?.parentId,\n      )(args);\n      attachReflection(proc, assembly.$reflectionMethods as ReflectionMethods);\n      if (opts?.awaitReady !== false) await proc.ready();\n      return proc as AsyncProcess<\n        Args,\n        HidePrivate<InternalState>,\n        InMsg,\n        OutMsg,\n        ReflectionMethods & ActorReflection\n      >;\n    },\n    async spawnAsChild(\n      ctx: ProcessCtx<unknown, unknown, OutMsg, Message>,\n      args: Args,\n      opts?: {\n        name?: string;\n        parentPlugins?: ActorPlugin[];\n        addPlugins?: ActorPlugin[];\n      },\n    ) {\n      const plugs = resolvePlugins(config.plugins, opts?.parentPlugins, opts?.addPlugins);\n      const assembly = await assembleActor(config, plugs, opts?.addPlugins);\n      const runtime = makeRuntime(assembly);\n      const proc = ctx.fork(runtime, opts?.name ?? assembly.name ?? \"child\")(args);\n      attachReflection(proc, assembly.$reflectionMethods as ReflectionMethods);\n      return proc as AsyncProcess<\n        Args,\n        HidePrivate<InternalState>,\n        InMsg,\n        OutMsg,\n        ReflectionMethods & ActorReflection\n      >;\n    },\n  };\n}\n"],"mappings":"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"}

package/dist/index.d.ts

@@ -20,7 +20,7 @@ declare function defineActor<Args, InternalState, InMsg extends Message, OutMsg
 //#endregion
 //#region src/version.d.ts
 /** posipaki's release version.  Must equal package.json's `version`. */
-declare const LIB_VERSION = "0.37.0";
+declare const LIB_VERSION = "0.38.0";
 //#endregion
 export { type ActorConfig, type ActorContext, type ActorDecorated, type ActorDefinition, type ActorPlugin, type ActorReflection, type AnyProcess, AsyncProcess, type AsyncProcessFn, type ExitMessage, type HandlerFn, type HandlerOptions, type HookResult, LIB_VERSION, type Message, type MethodOptions, type PluginTransform, Process, type ProcessCtx, type ProcessFn, type SenderInfo, type SenderOrigin, type SpawnedFrom, type StopMessage, type WithSender, type WithoutSender, asyncify, callHook, chainHook, defineActor, defineMessages, mergeConfigs, propagateError, runDispatch, runDispatchAsync, spawn, spawnAsync, stopPropagation };
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -1,7 +1,8 @@
 import { i as runDispatch } from "./util-Brtfgv68.js";
-import { a as runDispatchAsync, n as defineMessages, o as spawnAsync, r as AsyncProcess, s as asyncify, t as defineActor } from "./define-actor-CZysIKH4.js";
+import { a as spawnAsync, i as runDispatchAsync, o as asyncify, t as AsyncProcess } from "./process.async-CdQ_zpKp.js";
 import { n as chainHook, o as propagateError, r as mergeConfigs, s as stopPropagation, t as callHook } from "./hooks-CgXhmY4r.js";
-import { t as LIB_VERSION } from "./version-DTvG9uAx.js";
+import { n as defineMessages, t as defineActor } from "./define-actor-CCJy7LDp.js";
+import { t as LIB_VERSION } from "./version-BnBkASor.js";
 //#region src/process.ts
 /** @deprecated Use {@link spawnAsync} instead. */
 function spawn(fn, pname, tp) {

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","names":[],"sources":["../src/process.ts","../src/index.ts"],"sourcesContent":["import { AsyncProcess } from \"./process.async.js\";\nimport { asyncify } from \"./adapters.js\";\nimport type { Message, SenderInfo, ExitMessage, ProcessFn } from \"./types.js\";\n\nexport type { Message, ProcessFn, ProcessCtx } from \"./types.js\";\nexport { runDispatch } from \"./util.js\";\n\n/** @deprecated Use {@link spawnAsync} instead. */\nexport function spawn<A, S, IM extends Message = Message, OM extends Message = ExitMessage>(\n  fn: ProcessFn<A, S, IM, OM>,\n  pname: string,\n  tp?: (m: OM, from: SenderInfo) => void,\n): (a: A) => Process<A, S, IM, OM> {\n  return (a: A) => new Process(fn, pname, tp).start(a);\n}\n\n/** @deprecated Use {@link AsyncProcess} instead. Sync processes are\n *  wrapped via asyncify internally; spawnAsync handles both. */\nclass Process<A, S, IM extends Message, OM extends Message> extends AsyncProcess<A, S, IM, OM, {}> {\n  constructor(fn: ProcessFn<A, S, IM, OM>, pname: string, tp?: (m: OM, from: SenderInfo) => void) {\n    super(asyncify(fn), pname, tp);\n  }\n\n  start(a: A) {\n    super.start(a);\n    return this;\n  }\n  tick(): Promise<void> {\n    return super.pvtTick();\n  }\n}\n\nexport { Process };\n","/**\n * Posipaki — Erlang-inspired lightweight actor processes built on\n * generator functions. Processes communicate via message-passing,\n * can fork children, and expose their state reactively.\n *\n * @module\n */\n\nimport { Process, spawn } from \"./process.js\";\nimport { runDispatch } from \"./util.js\";\nimport { AsyncProcess, spawnAsync, runDispatchAsync } from \"./process.async.js\";\nimport { asyncify } from \"./adapters.js\";\n\nexport { Process, spawn, runDispatch };\nexport { AsyncProcess, spawnAsync, runDispatchAsync, asyncify };\nexport type { AnyProcess } from \"./process.async.js\";\n\nexport type {\n  Message,\n  WithSender,\n  WithoutSender,\n  ExitMessage,\n  StopMessage,\n  ProcessFn,\n  ProcessCtx,\n  AsyncProcessFn,\n  SenderOrigin,\n  SenderInfo,\n} from \"./types.js\";\n\nexport { defineActor, defineMessages } from \"./define-actor.js\";\nexport type {\n  ActorDefinition,\n  SpawnedFrom,\n  ActorConfig,\n  ActorContext,\n  MethodOptions,\n  HandlerOptions,\n  HandlerFn,\n} from \"./actor-types.js\";\n\n// ── hooks ─────────────────────────────────────────────────────────────────\n\nexport { stopPropagation, propagateError, mergeConfigs, chainHook, callHook } from \"./hooks.js\";\nexport type {\n  HookResult,\n  ActorPlugin,\n  ActorDecorated,\n  ActorReflection,\n  PluginTransform,\n} from \"./hooks.js\";\nexport { LIB_VERSION } from \"./version.js\";\n"],"mappings":";;;;;;AAQA,SAAgB,MACd,IACA,OACA,IACiC;CACjC,QAAQ,MAAS,IAAI,QAAQ,IAAI,OAAO,EAAE,CAAC,CAAC,MAAM,CAAC;AACrD;;;AAIA,IAAM,UAAN,cAAoE,aAA+B;CACjG,YAAY,IAA6B,OAAe,IAAwC;EAC9F,MAAM,SAAS,EAAE,GAAG,OAAO,EAAE;CAC/B;CAEA,MAAM,GAAM;EACV,MAAM,MAAM,CAAC;EACb,OAAO;CACT;CACA,OAAsB;EACpB,OAAO,MAAM,QAAQ;CACvB;AACF"}
+{"version":3,"file":"index.js","names":[],"sources":["../src/process.ts","../src/index.ts"],"sourcesContent":["import { AsyncProcess } from \"./process.async.js\";\nimport { asyncify } from \"./adapters.js\";\nimport type { Message, SenderInfo, ExitMessage, ProcessFn } from \"./types.js\";\n\nexport type { Message, ProcessFn, ProcessCtx } from \"./types.js\";\nexport { runDispatch } from \"./util.js\";\n\n/** @deprecated Use {@link spawnAsync} instead. */\nexport function spawn<A, S, IM extends Message = Message, OM extends Message = ExitMessage>(\n  fn: ProcessFn<A, S, IM, OM>,\n  pname: string,\n  tp?: (m: OM, from: SenderInfo) => void,\n): (a: A) => Process<A, S, IM, OM> {\n  return (a: A) => new Process(fn, pname, tp).start(a);\n}\n\n/** @deprecated Use {@link AsyncProcess} instead. Sync processes are\n *  wrapped via asyncify internally; spawnAsync handles both. */\nclass Process<A, S, IM extends Message, OM extends Message> extends AsyncProcess<A, S, IM, OM, {}> {\n  constructor(fn: ProcessFn<A, S, IM, OM>, pname: string, tp?: (m: OM, from: SenderInfo) => void) {\n    super(asyncify(fn), pname, tp);\n  }\n\n  start(a: A) {\n    super.start(a);\n    return this;\n  }\n  tick(): Promise<void> {\n    return super.pvtTick();\n  }\n}\n\nexport { Process };\n","/**\n * Posipaki — Erlang-inspired lightweight actor processes built on\n * generator functions. Processes communicate via message-passing,\n * can fork children, and expose their state reactively.\n *\n * @module\n */\n\nimport { Process, spawn } from \"./process.js\";\nimport { runDispatch } from \"./util.js\";\nimport { AsyncProcess, spawnAsync, runDispatchAsync } from \"./process.async.js\";\nimport { asyncify } from \"./adapters.js\";\n\nexport { Process, spawn, runDispatch };\nexport { AsyncProcess, spawnAsync, runDispatchAsync, asyncify };\nexport type { AnyProcess } from \"./process.async.js\";\n\nexport type {\n  Message,\n  WithSender,\n  WithoutSender,\n  ExitMessage,\n  StopMessage,\n  ProcessFn,\n  ProcessCtx,\n  AsyncProcessFn,\n  SenderOrigin,\n  SenderInfo,\n} from \"./types.js\";\n\nexport { defineActor, defineMessages } from \"./define-actor.js\";\nexport type {\n  ActorDefinition,\n  SpawnedFrom,\n  ActorConfig,\n  ActorContext,\n  MethodOptions,\n  HandlerOptions,\n  HandlerFn,\n} from \"./actor-types.js\";\n\n// ── hooks ─────────────────────────────────────────────────────────────────\n\nexport { stopPropagation, propagateError, mergeConfigs, chainHook, callHook } from \"./hooks.js\";\nexport type {\n  HookResult,\n  ActorPlugin,\n  ActorDecorated,\n  ActorReflection,\n  PluginTransform,\n} from \"./hooks.js\";\nexport { LIB_VERSION } from \"./version.js\";\n"],"mappings":";;;;;;;AAQA,SAAgB,MACd,IACA,OACA,IACiC;CACjC,QAAQ,MAAS,IAAI,QAAQ,IAAI,OAAO,EAAE,CAAC,CAAC,MAAM,CAAC;AACrD;;;AAIA,IAAM,UAAN,cAAoE,aAA+B;CACjG,YAAY,IAA6B,OAAe,IAAwC;EAC9F,MAAM,SAAS,EAAE,GAAG,OAAO,EAAE;CAC/B;CAEA,MAAM,GAAM;EACV,MAAM,MAAM,CAAC;EACb,OAAO;CACT;CACA,OAAsB;EACpB,OAAO,MAAM,QAAQ;CACvB;AACF"}

package/dist/{json1-CWWXL69y.js → json1-DZ8N0TuZ.js}

@@ -1,6 +1,7 @@
 import { r as makeWaiter } from "./util-Brtfgv68.js";
-import { i as isProcess, t as defineActor } from "./define-actor-CZysIKH4.js";
+import { r as isProcess } from "./process.async-CdQ_zpKp.js";
 import { s as stopPropagation } from "./hooks-CgXhmY4r.js";
+import { t as defineActor } from "./define-actor-CCJy7LDp.js";
 //#region src/remote/process-ref.ts
 /** The key that marks a process reference inside an otherwise JSON value. */
 const PROCESS_REF = "$p";
@@ -13,8 +14,10 @@ const PROCESS_REF = "$p";
 function rootIdFor(parity) {
 	return parity === "odd" ? 1 : 0;
 }
-/** The name a served root is spawned under: what a visitor's handle on the far root
-*  is called, since no frame about a root carries a name of its own. */
+/** What a served root is called when the client states no name for it.  A client that
+*  states one — and the library's own does, in `$init` — is served under that name instead:
+*  the process across the seam is the one its proxy was forked as, and it should be called
+*  the same on both sides.  This is the name for a connection that says nothing. */
 const SERVED_ROOT_NAME = "remote";
 /**
 * The processes one connection knows, by the ids that name them.  One table per
@@ -338,6 +341,42 @@ function jsonProblem(value) {
 }
 //#endregion
 //#region src/remote/remote-process.ts
+/**
+* What a reference with nothing keeping it amounts to.  It names a process this side can
+* hear nothing from and ask nothing of, so it is not a process in any sense that matters
+* here, and it is written as what it is wherever it turns up: a state somebody is reading,
+* a log line, anything at all that stringifies.
+*/
+const UNSTABLE_REFERENCE = "UnstableReference";
+/** What a process left behind when it ended. */
+/**
+* The references inside a value that crossed.  A handle is the one thing in a frame that is
+* not JSON, so wherever one sits, it came here on somebody else's frame and whoever is
+* holding that value is holding it.  Plain objects and arrays only: a value of another kind
+* is not a shape this walks, and its references are not found.
+*/
+function refsInside(value) {
+	const found = [];
+	const seen = /* @__PURE__ */ new Set();
+	const walk = (node) => {
+		if (isRemoteProcess(node)) {
+			found.push(node);
+			return;
+		}
+		if (typeof node !== "object" || node === null) return;
+		if (seen.has(node)) return;
+		seen.add(node);
+		if (Array.isArray(node)) {
+			for (const item of node) walk(item);
+			return;
+		}
+		const proto = Object.getPrototypeOf(node);
+		if (proto !== Object.prototype && proto !== null) return;
+		for (const item of Object.values(node)) walk(item);
+	};
+	walk(value);
+	return found;
+}
 var RemoteProcess = class {
 	constructor(ref, send, fromName, letGo) {
 		this.state = null;
@@ -348,6 +387,10 @@ var RemoteProcess = class {
 		this.pvtExitWaiter = null;
 		this.pvtMessageSubs = [];
 		this.pvtStateSubs = [];
+		this.pvtReadyWaiters = [];
+		this.pvtRefCount = 0;
+		this.pvtOwnedRefs = [];
+		this.pvtTransientRefs = [];
 		this.pvtWanted = /* @__PURE__ */ new Set();
 		this.ref = ref;
 		this.pname = ref.pname;
@@ -378,6 +421,7 @@ var RemoteProcess = class {
 		if (!this.pvtConnected) return;
 		this.pvtConnected = false;
 		this.pvtStateSubs.forEach((fn) => fn());
+		this.pvtSettleReady();
 		this.pvtExitWaiter?.reject(/* @__PURE__ */ new Error(`${this.pname} cannot be reached: the connection is closed`));
 	}
 	/** Whether the process it names has ended, as far as this side has been told. */
@@ -398,6 +442,121 @@ var RemoteProcess = class {
 		if (why !== null) throw new Error(why);
 	}
 	/**
+	* Keep this reference: from here it is counted, which is what lets anything be asked of
+	* it.  It returns the handle, so what is kept is written in one line —
+	* `this.pvtRemoteRefsHeld.push(ref.holdRef())` — and a table of them reads as what it is.
+	*/
+	holdRef() {
+		this.pvtRefCount += 1;
+		return this;
+	}
+	/**
+	* Give the count back.  Whoever gives the last one back lets the reference go, which is
+	* what tells the far side that nothing here wants to hear about the process again.  A
+	* reference nobody ever kept is let go of by this too, which is how whoever receives one
+	* they do not want is rid of it.
+	*/
+	releaseRef() {
+		if (this.pvtRefCount > 0) this.pvtRefCount -= 1;
+		if (this.pvtRefCount > 0) return;
+		if (this.pvtWhyNotAskable() === null) {
+			this.release();
+			return;
+		}
+		this.pvtDropBinding();
+	}
+	/** Let go of the binding here without asking the far side for anything: what the process
+	*  was is over, or the wire that carried it is. */
+	pvtDropBinding() {
+		if (this.pvtReleased) return;
+		this.pvtReleased = true;
+		this.pvtLetGo?.(this.ref.id);
+		this.pvtSettleReady();
+	}
+	/** How many times this reference has been kept. */
+	refCount() {
+		return this.pvtRefCount;
+	}
+	/**
+	* What this is, as text: a handle nothing here keeps is an unstable reference and says
+	* so, and one that is kept says which process it names and by which id.
+	*/
+	[Symbol.for("nodejs.util.inspect.custom")]() {
+		return this.pvtRefCount === 0 ? UNSTABLE_REFERENCE : `RemoteProcess(${this.ref.id}: ${this.pname})`;
+	}
+	/**
+	* What this is, in JSON: the same reference the wire would carry, or the unstable thing
+	* it is when nothing keeps it.  Written so that an unheld reference cannot be mistaken
+	* for a process that merely looks odd in a state, and so that one that is kept reads as
+	* the reference it is rather than as whatever fields it happens to have.
+	*/
+	toJSON() {
+		if (this.pvtRefCount === 0) return UNSTABLE_REFERENCE;
+		return { ["$p"]: {
+			id: this.ref.id,
+			pname: this.pname
+		} };
+	}
+	/**
+	* Remember the references inside a value that arrived here to be passed on.  They are not
+	* counted — the receiver is the one to deal with them — and this is what keeps one from
+	* being nobody's for ever: when this handle is let go of, they are dropped with it.
+	*/
+	markTransient(value) {
+		for (const ref of refsInside(value)) {
+			if (ref.id === this.id || ref.pvtReleased) continue;
+			this.pvtDropTransient(ref);
+			if (this.pvtOwnedRefs.includes(ref) || this.pvtTransientRefs.includes(ref)) continue;
+			this.pvtTransientRefs.push(ref);
+		}
+	}
+	/** Stop treating a reference as one that was only passing through. */
+	pvtDropTransient(ref) {
+		const at = this.pvtTransientRefs.indexOf(ref);
+		if (at >= 0) this.pvtTransientRefs.splice(at, 1);
+	}
+	/**
+	* Keep the references sitting in what this process holds.  What it holds is here, so the
+	* thing keeping those references alive is this handle, and it holds them until it is let
+	* go of itself.
+	*/
+	pvtHoldOwned(value) {
+		for (const ref of refsInside(value)) {
+			if (ref.id === this.id || ref.pvtReleased) continue;
+			if (this.pvtOwnedRefs.includes(ref)) continue;
+			this.pvtDropTransient(ref);
+			this.pvtOwnedRefs.push(ref.holdRef());
+		}
+	}
+	/** Nothing is heard about a process nothing here keeps.  A subscription, a tuning and a
+	*  wait for the state are all ways of hearing, so they are where a reference has to have
+	*  been kept first — and where the mistake says what to do about it. */
+	pvtRequireHeld(what) {
+		if (this.pvtRefCount > 0) return;
+		throw new Error(`${this.pname} is not held by anyone here: call holdRef() to keep this reference, or releaseRef() to let it go, before ${what}`);
+	}
+	/**
+	* Wait until what it holds is here.
+	*
+	* A handle starts out knowing nothing about the process: the far side says what a
+	* process holds when something over here asks to hear it, so the asking and the waiting
+	* are one act, and this is both.  It settles with whatever has arrived when nothing more
+	* can: a process that has ended has said its last, and a connection that has gone has
+	* nothing left to say.  Asking twice is asking about what is already here.
+	*/
+	ready() {
+		if (this.state !== null || this.pvtWhyNotAskable() !== null) return Promise.resolve();
+		this.pvtRequireHeld("waiting for what it holds");
+		this.pvtWant("state");
+		return new Promise((resolve) => this.pvtReadyWaiters.push(resolve));
+	}
+	/** Everyone waiting for what it holds has heard it, or never will. */
+	pvtSettleReady() {
+		const waiting = this.pvtReadyWaiters;
+		this.pvtReadyWaiters = [];
+		for (const resolve of waiting) resolve();
+	}
+	/**
 	* Wait for the process to end.  Its exit crosses back like everything else it
 	* does, and what it left behind is the answer.
 	*
@@ -433,8 +592,15 @@ var RemoteProcess = class {
 	release() {
 		this.pvtRequireAskable();
 		this.pvtReleased = true;
+		const owned = this.pvtOwnedRefs;
+		this.pvtOwnedRefs = [];
+		for (const ref of owned) if (!ref.pvtReleased) ref.releaseRef();
+		const transient = this.pvtTransientRefs;
+		this.pvtTransientRefs = [];
+		for (const ref of transient) if (!ref.pvtReleased && ref.pvtRefCount === 0) ref.release();
 		this.pvtLetGo?.(this.ref.id);
 		this.pvtSend({ $release: {} }, this.ref.id);
+		this.pvtSettleReady();
 	}
 	/** Stop feeding it messages.  It is still there: `send` still reaches it. */
 	pause() {
@@ -458,6 +624,7 @@ var RemoteProcess = class {
 	*/
 	tune(kinds) {
 		this.pvtRequireAskable();
+		this.pvtRequireHeld("tuning what is heard about it");
 		this.pvtTune(kinds === "silent" ? [] : kinds);
 	}
 	/** Ask the far side to say exactly this much, and nothing when it is already
@@ -486,6 +653,7 @@ var RemoteProcess = class {
 		} }, this.ref.id);
 	}
 	subscribe(channel, cb) {
+		this.pvtRequireHeld(`subscribing to what it ${channel === "message" ? "says" : "holds"}`);
 		if (channel === "message") {
 			const fn = cb;
 			this.pvtMessageSubs.push(fn);
@@ -505,11 +673,14 @@ var RemoteProcess = class {
 	receiveState(state) {
 		if (this.pvtReleased) return;
 		this.state = Object.assign(this.state ?? {}, state);
+		this.pvtHoldOwned(state);
 		this.pvtStateSubs.forEach((fn) => fn());
+		this.pvtSettleReady();
 	}
 	/** A message it emitted. */
 	receiveMessage(msg, fromName) {
 		if (this.pvtReleased) return;
+		this.markTransient(msg);
 		this.pvtMessageSubs.forEach((fn) => fn(msg, fromName));
 	}
 	/** It has ended, and this is what it left behind.  The last thing said about a
@@ -519,12 +690,17 @@ var RemoteProcess = class {
 		if (this.pvtExit !== null || this.pvtReleased) return;
 		this.pvtExit = exit;
 		this.pvtExitWaiter?.resolve(exit);
+		this.pvtSettleReady();
 	}
 	/** The methods it can answer, as functions that ask it for an answer.  `call`
 	*  is the connection's own: a handle knows what to ask for, not how a call is
 	*  made or paired with its answer. */
 	receiveMethods(names, call) {
-		for (const name of names) this.$reflection[name] = (...args) => call(name, args);
+		for (const name of names) this.$reflection[name] = async (...args) => {
+			const value = await call(name, args);
+			this.markTransient(value);
+			return value;
+		};
 	}
 };
 //#endregion
@@ -714,9 +890,20 @@ var CallSide = class {
 			});
 		});
 	}
-	/** One function per announced name, on the surface whoever calls reads. */
+	/**
+	* One function per announced name, on the surface whoever calls reads.
+	*
+	* An answer that carries a reference hands it to whoever asked, which makes it theirs to
+	* deal with: the handle that was asked is told about it, so that one nobody keeps is let
+	* go of with that handle rather than being nobody's for ever.
+	*/
 	install(surface, methods, to) {
-		for (const method of methods) surface[method] = (...callArgs) => this.call(method, callArgs, to);
+		for (const method of methods) surface[method] = async (...callArgs) => {
+			const value = await this.call(method, callArgs, to);
+			const owner = this.pvtTable.farHandleFor(to);
+			if (isRemoteProcess(owner)) owner.markTransient(value);
+			return value;
+		};
 	}
 	/**
 	* An answer to a call this side made: the call waiting under that `seq` is settled
@@ -788,10 +975,12 @@ async function answerCall(call, target, write, table) {
 }
 //#endregion
 //#region src/remote/server.ts
-/** The name the served actor is spawned under, and the one it answers to as a
-*  sender when it talks to a process of the far side's.  A reference that names the
-*  root it serves is told apart from the far side's root by it. */
-const ROOT_NAME = SERVED_ROOT_NAME;
+/** The name the served actor is spawned under, and the one it answers to as a sender when
+*  it talks to a process of the far side's: what the client states in `$init`, since the
+*  process being served is the one its proxy was forked as over there.  The fallback is for
+*  a connection that states none — an older client, or a hand-written `$init` — where the
+*  far side's name for its own end is all there is to go on. */
+let rootName = SERVED_ROOT_NAME;
 async function serveRemoteActor(actor, spawner) {
 	const channel = await spawner();
 	const table = new ProcessTable("even", (proc, id) => streams.crossed(proc, id));
@@ -818,7 +1007,7 @@ async function serveRemoteActor(actor, spawner) {
 		if (held) return held;
 		const known = table.farHandleFor(ref.id);
 		if (isRemoteProcess(known)) return known;
-		const handle = new RemoteProcess(ref, sendTo, ROOT_NAME, (id) => table.release(id));
+		const handle = new RemoteProcess(ref, sendTo, rootName, (id) => table.release(id));
 		table.bindFar(ref.id, handle);
 		return handle;
 	};
@@ -833,12 +1022,14 @@ async function serveRemoteActor(actor, spawner) {
 	const initFrame = decodeFrame(waiting.shift(), handleFor);
 	if (!isInit(initFrame)) throw new Error("serveRemoteActor: expected $init");
 	const init = initFrame.$init;
+	const stated = init.rootName;
+	if (typeof stated === "string" && stated !== "") rootName = stated;
 	const parentName = init.parentName ?? null;
 	const parentIdName = init.parentIdName ?? null;
 	const parentId = parentIdName ? Symbol.for(parentIdName) : null;
 	const { parentName: _pn, parentIdName: _pid, ...initArgs } = init;
 	const proc = await actor.spawn(initArgs, {
-		name: ROOT_NAME,
+		name: rootName,
 		parentName,
 		parentId
 	});
@@ -881,7 +1072,7 @@ async function serveRemoteActor(actor, spawner) {
 		}
 		if (isStop(frame) || isPause(frame) || isResume(frame)) {
 			if (isProcess(mine)) {
-				const sender = makeSender(ROOT_NAME, parentName, parentId);
+				const sender = makeSender(rootName, parentName, parentId);
 				if (isStop(frame)) mine.stop({ from: sender });
 				else if (isPause(frame)) mine.pause();
 				else mine.resume();
@@ -923,7 +1114,8 @@ function remoteClient(name, spawner) {
 			const root = this.ctx;
 			table.bindRoot(root);
 			const channel = await spawner(args);
-			const fromName = name;
+			const fromName = this.ctx.pname;
+			const parentName = this.ctx.parentName ?? this.ctx.pname;
 			const streams = new ProcessStreams((frame, to) => sendTo(frame, to), table.rootId());
 			/** Put an encoded frame on the wire, and then say what it numbered.  A frame that
 			*  carried a reference has to be out first, or the far side hears about a process
@@ -938,8 +1130,9 @@ function remoteClient(name, spawner) {
 			};
 			sendTo({ $init: {
 				...args,
-				parentName: fromName,
-				parentIdName: fromName
+				rootName: fromName,
+				parentName,
+				parentIdName: parentName
 			} }, table.farRootId());
 			let currentState = {};
 			const calls = new CallSide(write, table);
@@ -969,9 +1162,10 @@ function remoteClient(name, spawner) {
 			*/
 			const farRoot = new RemoteProcess({
 				id: table.farRootId(),
-				pname: SERVED_ROOT_NAME
+				pname: fromName
 			}, sendTo, fromName, (id) => table.release(id));
 			table.bindFar(table.farRootId(), farRoot);
+			farRoot.holdRef();
 			let started = null;
 			const start = new Promise((resolve) => {
 				started = resolve;
@@ -1040,7 +1234,7 @@ function remoteClient(name, spawner) {
 				}
 				if (isStop(frame) || isPause(frame) || isResume(frame)) {
 					if (isProcess(mine)) {
-						if (isStop(frame)) mine.stop({ from: makeSender(name, null, null) });
+						if (isStop(frame)) mine.stop({ from: makeSender(fromName, null, null) });
 						else if (isPause(frame)) mine.pause();
 						else mine.resume();
 					}
@@ -1113,4 +1307,4 @@ function json1Channel(transport) {
 //#endregion
 export { isStop as _, remoteClient as a, rootIdFor as b, RemoteProcess as c, isMsg as d, isPause as f, isState as g, isResume as h, json1Channel as i, isExit as l, isRelease as m, decode as n, serveRemoteActor as o, isProto as p, encode as r, makeSender as s, VERSION as t, isInit as u, PROCESS_REF as v, isRemoteProcess as y };
 
-//# sourceMappingURL=json1-CWWXL69y.js.map
+//# sourceMappingURL=json1-DZ8N0TuZ.js.map