@xandreed/process-host 0.0.0-stage → 0.15.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Xand Reed
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,5 @@
-# Temporary Holding Version
+# @xandreed/process-host
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Efferent composable agent framework, 0.15.1. Node 24 or Bun.
+
+Documentation: https://github.com/xandreeddev/efferent

package/dist/index.d.ts

@@ -0,0 +1,14 @@
+export { PROCESS_PROTOCOL_VERSION, ProcessCommand, ProcessEvent, ProcessEventMode, ProcessRequestId } from "./process-protocol.entity.js";
+export { decodeProcessCommand, encodeProcessEvent, processProgressOf, processLifecycleOf } from "./process-protocol.entity.functions.js";
+export { ProcessPeer } from "./ports/process-peer.port.js";
+export { ProcessPeerError, ProcessPeerReason, ProcessPeerDirection, ProcessPeerOptions, PROCESS_PEER_DEFAULTS } from "./process-peer.entity.js";
+export { processPeerConformance } from "./process-peer.conformance.js";
+export type { ProcessPeerSubject, ProcessPeerFixture } from "./process-peer.conformance.js";
+export { StdioPeerLive } from "./stdio-peer.adapter.js";
+export type { StdioPeerOptions } from "./stdio-peer.adapter.js";
+export { ProcessHostConfig, ProcessHostError, processHostDefaults } from "./process-host.entity.js";
+export type { ProcessBinding, ProcessObservers, ProcessHostOptions, ProcessHostResult } from "./process-host.entity.js";
+export { serveProcess } from "./process-host.adapter.js";
+export { PROCESS_EXIT_CODES } from "./process-runtime.entity.js";
+export { runProcessHost } from "./process-runtime.adapter.js";
+export type { RunProcessHostOptions } from "./process-runtime.adapter.js";

package/dist/index.js

@@ -0,0 +1,10 @@
+export { PROCESS_PROTOCOL_VERSION, ProcessCommand, ProcessEvent, ProcessEventMode, ProcessRequestId } from "./process-protocol.entity.js";
+export { decodeProcessCommand, encodeProcessEvent, processProgressOf, processLifecycleOf } from "./process-protocol.entity.functions.js";
+export { ProcessPeer } from "./ports/process-peer.port.js";
+export { ProcessPeerError, ProcessPeerReason, ProcessPeerDirection, ProcessPeerOptions, PROCESS_PEER_DEFAULTS } from "./process-peer.entity.js";
+export { processPeerConformance } from "./process-peer.conformance.js";
+export { StdioPeerLive } from "./stdio-peer.adapter.js";
+export { ProcessHostConfig, ProcessHostError, processHostDefaults } from "./process-host.entity.js";
+export { serveProcess } from "./process-host.adapter.js";
+export { PROCESS_EXIT_CODES } from "./process-runtime.entity.js";
+export { runProcessHost } from "./process-runtime.adapter.js";

package/dist/ports/process-peer.port.d.ts

@@ -0,0 +1,22 @@
+import { Context } from "effect";
+import type { Effect, Stream } from "effect";
+import type { ProcessCommand, ProcessEvent } from "../process-protocol.entity.js";
+import type { ProcessPeerError } from "../process-peer.entity.js";
+declare const ProcessPeer_base: Context.ServiceClass<ProcessPeer, "@xandreed/process-host/ProcessPeer", {
+    readonly commands: Stream.Stream<ProcessCommand, ProcessPeerError>;
+    /** Accept and acknowledge one complete output frame, or fail without partial interleaving. */
+    readonly send: (event: ProcessEvent) => Effect.Effect<void, ProcessPeerError>;
+    /** Barrier for all writes accepted before this call; output failures remain failures. */
+    readonly flush: Effect.Effect<void, ProcessPeerError>;
+}>;
+/**
+ * One scoped, bounded, ordered NDJSON connection. `commands` has one lifetime
+ * consumer. Input EOF completes it only at a frame boundary. Accepted sends
+ * survive caller interruption; `flush` awaits every send accepted before its
+ * snapshot and preserves the first output failure. Closing the peer does not
+ * close host-owned native streams. `processPeerConformance` is the runnable contract.
+ * @public
+ */
+export declare class ProcessPeer extends ProcessPeer_base {
+}
+export {};

package/dist/ports/process-peer.port.js

@@ -0,0 +1,4 @@
+import { Context } from "effect";
+
+export class ProcessPeer extends Context.Service()("@xandreed/process-host/ProcessPeer") {
+}

package/dist/process-host.adapter.d.ts

@@ -0,0 +1,13 @@
+import { Effect } from "effect";
+import type { Scope } from "effect";
+import { ProcessPeer } from "./ports/process-peer.port.js";
+import { ProcessHostError } from "./process-host.entity.js";
+import type { ProcessHostOptions, ProcessHostResult } from "./process-host.entity.js";
+/**
+ * Serve one connection with a host-supplied runtime. Setup owns startup
+ * recovery and installs the observers before constructing its services.
+ * This scope keeps storage open through graceful shutdown and output ACKs.
+ * No native process exit or automatic task/drainer construction occurs here.
+ * @public
+ */
+export declare const serveProcess: <E>(options: ProcessHostOptions<E>) => Effect.Effect<ProcessHostResult, ProcessHostError, Scope.Scope | ProcessPeer>;

package/dist/process-host.adapter.js

@@ -0,0 +1,153 @@
+import { Clock, Context, Deferred, Effect, Fiber, FiberSet, Match, Option, Predicate, Ref, Result, Schema, Stream } from "effect";
+import { harnessCodeOf } from "@xandreed/core";
+import { ProcessPeer } from "./ports/process-peer.port.js";
+import { PROCESS_PROTOCOL_VERSION } from "./process-protocol.entity.js";
+import { processLifecycleOf, processProgressOf } from "./process-protocol.entity.functions.js";
+import { ProcessHostConfig, ProcessHostError, processHostDefaults } from "./process-host.entity.js";
+import { admitProcessRequest, endedProcessRequestOf, noteProcessTurn, openProcessDispatch, processRequestOf, releaseProcessRequest, stopProcessDispatch } from "./process-host.entity.functions.js";
+const peerFailure = (cause) => new ProcessHostError({
+  reason: cause.direction === "input" && ["InvalidFrame", "InvalidUtf8", "FrameTooLarge"].includes(cause.reason) ? "Protocol" : "Peer",
+  code: cause.direction === "input" && ["InvalidFrame", "InvalidUtf8", "FrameTooLarge"].includes(cause.reason) ? "protocol.invalid" : "host.peer",
+  message: cause.direction === "input" ? "the process input could not be read" : "the process output could not be written",
+  cause
+}), correlation = (requestId) => Option.match(requestId, { onNone: () => ({}), onSome: (requestId) => ({ requestId }) });
+export const serveProcess = Effect.fn("process.serve")(function* (options) {
+  const stoppingNotified = yield* Ref.make(!1), notifyStopping = Ref.getAndSet(stoppingNotified, !0).pipe(Effect.flatMap((already) => already ? Effect.void : options.onStopping ?? Effect.void));
+  return yield* Effect.scoped(Effect.gen(function* () {
+    const config = yield* Schema.decodeUnknownEffect(ProcessHostConfig)({
+      owners: options.owners,
+      events: options.events ?? processHostDefaults.events,
+      maxBegins: options.maxBegins ?? processHostDefaults.maxBegins,
+      maxShortCommands: options.maxShortCommands ?? processHostDefaults.maxShortCommands,
+      controlCapacity: options.controlCapacity ?? processHostDefaults.controlCapacity,
+      handshakeTimeoutMs: options.handshakeTimeoutMs ?? processHostDefaults.handshakeTimeoutMs,
+      shutdown: { ...processHostDefaults.shutdown, ...options.shutdown }
+    }).pipe(Effect.mapError((cause) => new ProcessHostError({ reason: "Config", code: "host.runtime", message: "invalid process host options", cause }))), peer = yield* ProcessPeer, state = yield* Ref.make({ _tag: "AwaitingHello", requests: [] }), binding = yield* Ref.make(Option.none()), failure = yield* Ref.make(Option.none()), stopped = yield* Deferred.make(), workers = yield* FiberSet.make(), stop = (request) => Effect.uninterruptible(Effect.gen(function* () {
+      if (!(yield* Ref.modify(state, (current) => [current._tag !== "Stopping", stopProcessDispatch(current)])))
+        return;
+      const notified = yield* Effect.exit(notifyStopping);
+      if (notified._tag === "Failure")
+        yield* Ref.update(failure, (current) => Option.isSome(current) ? current : Option.some(new ProcessHostError({ reason: "Runtime", code: "host.runtime", message: "the process stopping hook failed", cause: notified.cause })));
+      yield* Deferred.succeed(stopped, request);
+    })), fatal = (error, requestId) => Ref.update(failure, (current) => Option.isSome(current) ? current : Option.some(error)).pipe(Effect.andThen(stop({ reason: "eof", ...requestId === void 0 ? {} : { requestId } }))), send = (event) => peer.send(event).pipe(Effect.catch((error) => fatal(peerFailure(error))), Effect.catchDefect((cause) => fatal(new ProcessHostError({ reason: "Peer", code: "host.peer", message: "the process output failed", cause })))), refuse = (requestId, code, message, frameworkCode) => send({
+      _tag: "error",
+      requestId,
+      code,
+      message,
+      fatal: !1,
+      ...frameworkCode === void 0 ? {} : { frameworkCode }
+    }), progressOf = (event) => processProgressOf(event, config.events).pipe(Effect.catch((error) => config.events === "full" && error.reason === "InvalidEvent" ? Effect.logWarning("a turn event's full content is not JSON; its projection is sent instead").pipe(Effect.annotateLogs({ "efferent.event": event._tag }), Effect.andThen(processProgressOf(event, "projection"))) : Effect.fail(error))), observe = {
+      sessionLog: (inner) => ({
+        create: (header) => inner.create(header),
+        head: (id) => inner.head(id),
+        list: (query) => inner.list(query),
+        read: (id, query) => inner.read(id, query),
+        remove: (id) => inner.remove(id),
+        commit: (id, commit) => Effect.uninterruptibleMask((restore) => Effect.gen(function* () {
+          const header = (yield* restore(inner.head(id))).header, receipt = yield* restore(inner.commit(id, commit));
+          if (!config.owners.includes(header.owner))
+            return receipt;
+          const address = { id, owner: header.owner };
+          yield* Effect.forEach(receipt.events, (row) => processLifecycleOf(address, row).pipe(Effect.flatMap(Option.match({
+            onNone: () => Effect.void,
+            onSome: (event) => Match.value(event).pipe(Match.tag("turn.started", (started) => Ref.modify(state, (current) => [
+              processRequestOf(current, address, started.runId),
+              noteProcessTurn(current, address, started.runId, started.turn)
+            ]).pipe(Effect.flatMap((requestId) => send({ ...started, ...correlation(requestId) })))), Match.tag("turn.ended", (ended) => Ref.get(state).pipe(Effect.flatMap((current) => send({ ...ended, ...correlation(endedProcessRequestOf(current, address, ended.turn)) })))), Match.orElse(() => Effect.void))
+          })), Effect.catch((cause) => fatal(new ProcessHostError({ reason: "Runtime", code: "host.runtime", message: "a committed process lifecycle event could not be observed", cause }))), Effect.catchDefect((cause) => fatal(new ProcessHostError({ reason: "Runtime", code: "host.runtime", message: "a committed process lifecycle observation failed", cause })))), { concurrency: 1, discard: !0 });
+          return receipt;
+        }))
+      }),
+      turnRunner: (inner) => ({
+        turn: (input, use) => inner.turn(input, (turn) => Effect.gen(function* () {
+          const address = turn.admitted.session;
+          if (config.owners.includes(address.owner))
+            yield* turn.events.subscribe(Option.some, (event) => progressOf(event).pipe(Effect.flatMap(Option.match({ onNone: () => Effect.void, onSome: (progress) => Ref.get(state).pipe(Effect.flatMap((current) => send({
+              _tag: "turn.event",
+              session: address,
+              turn: turn.turn,
+              runId: turn.runId,
+              progress,
+              ...correlation(processRequestOf(current, address, turn.runId))
+            }))) })), Effect.catch((cause) => fatal(peerFailure(cause))), Effect.catchDefect((cause) => fatal(new ProcessHostError({ reason: "Peer", code: "host.peer", message: "a process progress event could not be observed", cause })))), { mode: "inline" });
+          return yield* use(turn);
+        }))
+      })
+    }, runCommand = (host, command) => Match.valueTags(command, {
+      hello: () => fatal(new ProcessHostError({ reason: "Protocol", code: "protocol.sequence", message: "hello is only accepted as the first command" }), command.requestId),
+      begin: (begin) => {
+        const { _tag, requestId, ...turn } = begin;
+        return host.runner.turn({ turn, services: host.services }, host.use).pipe(Effect.flatMap((result) => send({ _tag: "begin.result", requestId, result })));
+      },
+      send: (queued) => host.sessions.enqueue(queued.session, { ...queued.input, delivery: "next" }).pipe(Effect.flatMap((result) => send({ _tag: "queued", requestId: queued.requestId, command: "send", ...result }))),
+      steer: (queued) => host.sessions.enqueue(queued.session, { ...queued.input, delivery: "steer" }).pipe(Effect.flatMap((result) => send({ _tag: "queued", requestId: queued.requestId, command: "steer", ...result }))),
+      answer: (answer) => Option.match(host.tasks, {
+        onNone: () => refuse(answer.requestId, "host.unsupported", "task answers are not available in this host"),
+        onSome: (tasks) => tasks.answer(answer.parent, answer.taskId, { questionId: answer.questionId, text: answer.text }).pipe(Effect.flatMap((result) => send({ _tag: "answered", requestId: answer.requestId, ...result })))
+      }),
+      cancel: (cancel) => host.sessions.cancel(cancel.session, cancel.turn).pipe(Effect.flatMap((result) => send({ _tag: "cancelled", requestId: cancel.requestId, ...result }))),
+      ping: (ping) => host.activity.pipe(Effect.flatMap((activity) => send({ _tag: "pong", requestId: ping.requestId, activity }))),
+      shutdown: (shutdown) => stop({ reason: "shutdown", requestId: shutdown.requestId, ...shutdown.deadlineMs === void 0 ? {} : { deadlineMs: shutdown.deadlineMs } })
+    }).pipe(Effect.catch((error) => Predicate.isTagged(error, "SessionLogError") ? fatal(new ProcessHostError({ reason: "Runtime", code: "host.runtime", message: "the process storage operation failed", cause: error }), command.requestId) : refuse(command.requestId, "host.command", "the process command could not complete", Option.getOrUndefined(harnessCodeOf(error)))), Effect.catchDefect((cause) => fatal(new ProcessHostError({ reason: "Runtime", code: "host.runtime", message: "the process command failed", cause }), command.requestId))), dispatch = (host, command) => Effect.gen(function* () {
+      const active = {
+        requestId: command.requestId,
+        lane: Match.value(command).pipe(Match.tag("begin", () => "begin"), Match.tag("cancel", "ping", "shutdown", () => "control"), Match.orElse(() => "short")),
+        begin: Match.value(command).pipe(Match.tag("begin", (begin) => Option.some({ session: begin.session, runId: begin.runId, turn: Option.none() })), Match.orElse(() => Option.none()))
+      }, admitted = yield* Ref.modify(state, (current) => {
+        const next = admitProcessRequest(current, active, config);
+        return [next, Result.getOrElse(next, () => current)];
+      });
+      if (Result.isFailure(admitted))
+        return yield* Match.value(admitted.failure).pipe(Match.when("Duplicate", () => fatal(new ProcessHostError({ reason: "Protocol", code: "protocol.sequence", message: "a command request id is already outstanding" }), command.requestId)), Match.when("Stopping", () => refuse(command.requestId, "host.stopping", "the process host is stopping")), Match.when("Busy", () => refuse(command.requestId, "host.busy", "the process command capacity is full")), Match.exhaustive);
+      const address = Match.value(command).pipe(Match.tag("begin", "send", "steer", "cancel", (value) => Option.some(value.session)), Match.tag("answer", (value) => Option.some(value.parent)), Match.orElse(() => Option.none())), released = Ref.update(state, (current) => releaseProcessRequest(current, command.requestId));
+      if (Option.exists(address, (session) => !config.owners.includes(session.owner)))
+        return yield* refuse(command.requestId, "host.owner", "the session owner is not available in this host").pipe(Effect.ensuring(released));
+      if (command._tag === "shutdown") {
+        if (command.deadlineMs !== void 0 && command.deadlineMs > config.shutdown.deadlineMs)
+          return yield* refuse(command.requestId, "host.command", "the shutdown deadline exceeds the host maximum").pipe(Effect.ensuring(released));
+        return yield* runCommand(host, command);
+      }
+      yield* FiberSet.run(workers, runCommand(host, command).pipe(Effect.ensuring(released)));
+    }), accept = (command) => Effect.gen(function* () {
+      if ((yield* Ref.get(state))._tag === "AwaitingHello") {
+        if (command._tag !== "hello")
+          return yield* fatal(new ProcessHostError({ reason: "Protocol", code: "protocol.handshake", message: "the first process command must be hello" }), command.requestId);
+        if (command.protocolVersion !== PROCESS_PROTOCOL_VERSION)
+          return yield* fatal(new ProcessHostError({ reason: "Protocol", code: "protocol.version", message: "the process protocol version is unsupported" }), command.requestId);
+        yield* Ref.set(state, { _tag: "Starting", requests: [] });
+        yield* send({ _tag: "hello", requestId: command.requestId, protocolVersion: PROCESS_PROTOCOL_VERSION });
+        if ((yield* Ref.get(state))._tag === "Stopping")
+          return;
+        const built = yield* options.setup(observe).pipe(Effect.map(Option.some), Effect.catch((cause) => fatal(new ProcessHostError({ reason: "Setup", code: "host.setup", message: "the process host could not be set up", cause })).pipe(Effect.as(Option.none()))), Effect.catchDefect((cause) => fatal(new ProcessHostError({ reason: "Setup", code: "host.setup", message: "the process host setup failed", cause })).pipe(Effect.as(Option.none()))));
+        if (Option.isSome(built)) {
+          yield* Ref.set(binding, built);
+          yield* Ref.update(state, openProcessDispatch);
+        }
+        return;
+      }
+      const host = yield* Ref.get(binding);
+      if (Option.isSome(host))
+        return yield* dispatch(host.value, command);
+    }), reader = yield* peer.commands.pipe(Stream.runForEach(accept), Effect.andThen(Ref.get(state).pipe(Effect.flatMap((current) => current._tag === "AwaitingHello" ? fatal(new ProcessHostError({ reason: "Protocol", code: "protocol.handshake", message: "the process input ended before hello" })) : stop({ reason: "eof" })))), Effect.catch((cause) => fatal(peerFailure(cause))), Effect.catchDefect((cause) => fatal(new ProcessHostError({ reason: "Runtime", code: "host.runtime", message: "the process command reader failed", cause }))), Effect.forkScoped);
+    yield* Effect.sleep(config.handshakeTimeoutMs).pipe(Effect.andThen(Ref.get(state)), Effect.flatMap((current) => current._tag === "AwaitingHello" ? fatal(new ProcessHostError({ reason: "Protocol", code: "protocol.handshake", message: "the process hello deadline expired" })) : Effect.void), Effect.forkScoped);
+    yield* (options.stop ?? Effect.never).pipe(Effect.andThen(stop({ reason: "signal" })), Effect.catchDefect((cause) => fatal(new ProcessHostError({ reason: "Runtime", code: "host.runtime", message: "the process stop signal failed", cause }))), Effect.forkScoped);
+    const request = yield* Deferred.await(stopped);
+    yield* Effect.forkScoped(Fiber.interrupt(reader));
+    const host = yield* Ref.get(binding), shutdownStarted = yield* Clock.currentTimeMillis, report = yield* Option.match(host, {
+      onNone: () => Effect.succeed(Option.none()),
+      onSome: (host) => host.shutdown({ deadline: request.deadlineMs ?? config.shutdown.deadlineMs, reserve: Math.min(config.shutdown.reserveMs, request.deadlineMs ?? config.shutdown.deadlineMs) }).pipe(Effect.map(Option.some), Effect.catchDefect((cause) => fatal(new ProcessHostError({ reason: "Runtime", code: "host.runtime", message: "the process shutdown failed", cause })).pipe(Effect.as(Option.none()))))
+    }), remaining = Math.max(0, (request.deadlineMs ?? config.shutdown.deadlineMs) - ((yield* Clock.currentTimeMillis) - shutdownStarted)), responses = yield* FiberSet.awaitEmpty(workers).pipe(Effect.timeoutOption(Math.min(config.shutdown.reserveMs, remaining)));
+    if (Option.isNone(responses))
+      yield* FiberSet.clear(workers);
+    if (Option.isSome(report))
+      yield* send({ _tag: "shutdown", ...correlation(Option.fromNullishOr(request.requestId)), report: report.value });
+    const failed = yield* Ref.get(failure);
+    if (Option.isSome(failed))
+      yield* peer.send({ _tag: "error", ...correlation(Option.fromNullishOr(request.requestId)), code: failed.value.code, message: failed.value.message, fatal: !0 }).pipe(Effect.catch((cause) => Effect.logWarning("the process peer could not report the host failure").pipe(Effect.andThen(fatal(peerFailure(cause))))), Effect.catchDefect((cause) => fatal(new ProcessHostError({ reason: "Peer", code: "host.peer", message: "the process failure could not be written", cause }))));
+    yield* peer.flush.pipe(Effect.catch((cause) => fatal(peerFailure(cause))), Effect.catchDefect((cause) => fatal(new ProcessHostError({ reason: "Peer", code: "host.peer", message: "the process output could not be flushed", cause }))));
+    const finalFailure = yield* Ref.get(failure);
+    if (Option.isSome(finalFailure))
+      return yield* Effect.fail(finalFailure.value);
+    return { reason: request.reason, report };
+  }).pipe(Effect.onExit(() => notifyStopping)));
+});

package/dist/process-host.entity.d.ts

@@ -0,0 +1,128 @@
+import { Schema } from "effect";
+import type { Context, Effect, Option, Scope } from "effect";
+import type { ProcessActivity, SessionLog, SessionLogError, Sessions, ShutdownOptions, ShutdownReport, Tasks, Turn, TurnError, TurnOutcome, TurnRunner, TurnServices } from "@xandreed/core";
+/** Services captured from the same host scope as every direct, queued and task turn. @public */
+export interface ProcessBinding {
+    readonly runner: TurnRunner;
+    readonly services: Context.Context<never>;
+    readonly use: (turn: Turn) => Effect.Effect<TurnOutcome, TurnError, TurnServices | Scope.Scope>;
+    readonly sessions: Context.Service.Shape<typeof Sessions>;
+    readonly tasks: Option.Option<Context.Service.Shape<typeof Tasks>>;
+    readonly activity: Effect.Effect<ProcessActivity, SessionLogError>;
+    readonly shutdown: (options: ShutdownOptions) => Effect.Effect<ShutdownReport>;
+}
+/** Install both wrappers before constructing the host's Sessions, Agent and bridges. @public */
+export interface ProcessObservers {
+    readonly sessionLog: (inner: Context.Service.Shape<typeof SessionLog>) => Context.Service.Shape<typeof SessionLog>;
+    readonly turnRunner: (inner: TurnRunner) => TurnRunner;
+}
+/** Bounded command admission; transport byte and native write limits belong to StdioPeerLive. @public */
+export declare const ProcessHostConfig: Schema.Struct<{
+    readonly owners: Schema.$Array<Schema.Trimmed>;
+    readonly events: Schema.Literals<readonly ["projection", "full"]>;
+    readonly maxBegins: Schema.Int;
+    readonly maxShortCommands: Schema.Int;
+    readonly controlCapacity: Schema.Int;
+    readonly handshakeTimeoutMs: Schema.Int;
+    readonly shutdown: Schema.Struct<{
+        readonly deadlineMs: Schema.Int;
+        readonly reserveMs: Schema.Int;
+    }>;
+}>;
+export type ProcessHostConfig = typeof ProcessHostConfig.Type;
+/** @public */
+export declare const processHostDefaults: Omit<ProcessHostConfig, "owners">;
+/** The parent supplies setup and explicitly owns startup reconciliation/takeover policy. @public */
+export interface ProcessHostOptions<E = never> extends Partial<Omit<ProcessHostConfig, "owners" | "shutdown">> {
+    readonly owners: ProcessHostConfig["owners"];
+    readonly shutdown?: Partial<ProcessHostConfig["shutdown"]>;
+    readonly setup: (observe: ProcessObservers) => Effect.Effect<ProcessBinding, E, Scope.Scope>;
+    /** A native signal or an embedding host's stop request; it may complete before setup. */
+    readonly stop?: Effect.Effect<void>;
+    /** Runs once before shutdown/teardown can block, so the native edge can start its hard timer. */
+    readonly onStopping?: Effect.Effect<void>;
+}
+/** No native exit occurs in serveProcess; a signal before setup has no shutdown report. @public */
+export interface ProcessHostResult {
+    readonly reason: "shutdown" | "eof" | "signal";
+    readonly report: Option.Option<ShutdownReport>;
+}
+declare const ProcessHostError_base: Schema.Class<ProcessHostError, Schema.TaggedStruct<"ProcessHostError", {
+    readonly reason: Schema.Literals<readonly ["Config", "Protocol", "Setup", "Peer", "Runtime"]>;
+    readonly code: Schema.Literals<readonly ["protocol.handshake", "protocol.version", "protocol.sequence", "protocol.invalid", "host.busy", "host.owner", "host.stopping", "host.unsupported", "host.command", "host.setup", "host.runtime", "host.peer"]>;
+    readonly message: Schema.String;
+    readonly cause: Schema.optional<Schema.Defect>;
+}>, import("effect/Cause").YieldableError>;
+/** Safe host failure; raw causes remain local and are never sent as wire messages. @public */
+export declare class ProcessHostError extends ProcessHostError_base {
+}
+/** Internal bounded command identity; no model messages or attachment bytes are retained here. */
+export declare const ProcessActiveRequest: Schema.Struct<{
+    readonly requestId: Schema.brand<Schema.Trimmed, "ProcessRequestId">;
+    readonly lane: Schema.Literals<readonly ["begin", "short", "control"]>;
+    readonly begin: Schema.OptionFromNullOr<Schema.Struct<{
+        readonly session: Schema.Struct<{
+            readonly id: Schema.brand<Schema.String, "ConversationId">;
+            readonly owner: Schema.Trimmed;
+        }>;
+        readonly runId: Schema.brand<Schema.String, "RunId">;
+        readonly turn: Schema.OptionFromNullOr<Schema.Int>;
+    }>>;
+}>;
+export type ProcessActiveRequest = typeof ProcessActiveRequest.Type;
+/** The dispatcher transitions this aggregate atomically, then performs side effects. */
+export declare const ProcessDispatchState: Schema.toTaggedUnion<"_tag", readonly [Schema.TaggedStruct<"AwaitingHello", {
+    readonly requests: Schema.$Array<Schema.Struct<{
+        readonly requestId: Schema.brand<Schema.Trimmed, "ProcessRequestId">;
+        readonly lane: Schema.Literals<readonly ["begin", "short", "control"]>;
+        readonly begin: Schema.OptionFromNullOr<Schema.Struct<{
+            readonly session: Schema.Struct<{
+                readonly id: Schema.brand<Schema.String, "ConversationId">;
+                readonly owner: Schema.Trimmed;
+            }>;
+            readonly runId: Schema.brand<Schema.String, "RunId">;
+            readonly turn: Schema.OptionFromNullOr<Schema.Int>;
+        }>>;
+    }>>;
+}>, Schema.TaggedStruct<"Starting", {
+    readonly requests: Schema.$Array<Schema.Struct<{
+        readonly requestId: Schema.brand<Schema.Trimmed, "ProcessRequestId">;
+        readonly lane: Schema.Literals<readonly ["begin", "short", "control"]>;
+        readonly begin: Schema.OptionFromNullOr<Schema.Struct<{
+            readonly session: Schema.Struct<{
+                readonly id: Schema.brand<Schema.String, "ConversationId">;
+                readonly owner: Schema.Trimmed;
+            }>;
+            readonly runId: Schema.brand<Schema.String, "RunId">;
+            readonly turn: Schema.OptionFromNullOr<Schema.Int>;
+        }>>;
+    }>>;
+}>, Schema.TaggedStruct<"Open", {
+    readonly requests: Schema.$Array<Schema.Struct<{
+        readonly requestId: Schema.brand<Schema.Trimmed, "ProcessRequestId">;
+        readonly lane: Schema.Literals<readonly ["begin", "short", "control"]>;
+        readonly begin: Schema.OptionFromNullOr<Schema.Struct<{
+            readonly session: Schema.Struct<{
+                readonly id: Schema.brand<Schema.String, "ConversationId">;
+                readonly owner: Schema.Trimmed;
+            }>;
+            readonly runId: Schema.brand<Schema.String, "RunId">;
+            readonly turn: Schema.OptionFromNullOr<Schema.Int>;
+        }>>;
+    }>>;
+}>, Schema.TaggedStruct<"Stopping", {
+    readonly requests: Schema.$Array<Schema.Struct<{
+        readonly requestId: Schema.brand<Schema.Trimmed, "ProcessRequestId">;
+        readonly lane: Schema.Literals<readonly ["begin", "short", "control"]>;
+        readonly begin: Schema.OptionFromNullOr<Schema.Struct<{
+            readonly session: Schema.Struct<{
+                readonly id: Schema.brand<Schema.String, "ConversationId">;
+                readonly owner: Schema.Trimmed;
+            }>;
+            readonly runId: Schema.brand<Schema.String, "RunId">;
+            readonly turn: Schema.OptionFromNullOr<Schema.Int>;
+        }>>;
+    }>>;
+}>]>;
+export type ProcessDispatchState = typeof ProcessDispatchState.Type;
+export {};

package/dist/process-host.entity.functions.d.ts

@@ -0,0 +1,12 @@
+import { Option, Result } from "effect";
+import type { RunId, SessionAddress } from "@xandreed/core";
+import type { ProcessRequestId } from "./process-protocol.entity.js";
+import type { ProcessActiveRequest, ProcessDispatchState, ProcessHostConfig } from "./process-host.entity.js";
+/** Decide admission without blocking the reader behind a running command. */
+export declare const admitProcessRequest: (state: ProcessDispatchState, request: ProcessActiveRequest, config: ProcessHostConfig) => Result.Result<ProcessDispatchState, "Duplicate" | "Stopping" | "Busy">;
+export declare const openProcessDispatch: (state: ProcessDispatchState) => ProcessDispatchState;
+export declare const stopProcessDispatch: (state: ProcessDispatchState) => ProcessDispatchState;
+export declare const releaseProcessRequest: (state: ProcessDispatchState, requestId: ProcessRequestId) => ProcessDispatchState;
+export declare const processRequestOf: (state: ProcessDispatchState, session: SessionAddress, runId: RunId) => Option.Option<ProcessRequestId>;
+export declare const noteProcessTurn: (state: ProcessDispatchState, session: SessionAddress, runId: RunId, turn: number) => ProcessDispatchState;
+export declare const endedProcessRequestOf: (state: ProcessDispatchState, session: SessionAddress, turn: number) => Option.Option<ProcessRequestId>;

package/dist/process-host.entity.functions.js

@@ -0,0 +1,17 @@
+import { Match, Option, Result } from "effect";
+export const admitProcessRequest = (state, request, config) => {
+  if (state.requests.some((active) => active.requestId === request.requestId))
+    return Result.fail("Duplicate");
+  return Match.value(state).pipe(Match.tag("Open", (open) => {
+    const maximum = { begin: config.maxBegins, short: config.maxShortCommands, control: config.controlCapacity }[request.lane];
+    if (open.requests.filter((active) => active.lane === request.lane).length >= maximum)
+      return Result.fail("Busy");
+    return Result.succeed({ ...open, requests: [...open.requests, request] });
+  }), Match.orElse(() => Result.fail("Stopping")));
+}, openProcessDispatch = (state) => Match.value(state).pipe(Match.tag("Stopping", (stopping) => stopping), Match.orElse((current) => ({ _tag: "Open", requests: current.requests }))), stopProcessDispatch = (state) => ({ _tag: "Stopping", requests: state.requests }), releaseProcessRequest = (state, requestId) => ({ ...state, requests: state.requests.filter((request) => request.requestId !== requestId) }), processRequestOf = (state, session, runId) => {
+  const candidates = state.requests.filter((request) => Option.exists(request.begin, (begin) => begin.session.id === session.id && begin.session.owner === session.owner && begin.runId === runId));
+  return candidates.length === 1 ? Option.fromNullishOr(candidates[0]).pipe(Option.map((request) => request.requestId)) : Option.none();
+}, noteProcessTurn = (state, session, runId, turn) => {
+  const requestId = processRequestOf(state, session, runId);
+  return { ...state, requests: state.requests.map((request) => Option.contains(requestId, request.requestId) ? { ...request, begin: Option.map(request.begin, (begin) => ({ ...begin, turn: Option.some(turn) })) } : request) };
+}, endedProcessRequestOf = (state, session, turn) => Option.fromNullishOr(state.requests.find((request) => Option.exists(request.begin, (begin) => begin.session.id === session.id && begin.session.owner === session.owner && Option.contains(begin.turn, turn)))).pipe(Option.map((request) => request.requestId));

package/dist/process-host.entity.js

@@ -0,0 +1,38 @@
+import { Schema } from "effect";
+import { ProcessErrorCode, ProcessEventMode, ProcessRequestId } from "./process-protocol.entity.js";
+import { RunId, SessionAddress } from "@xandreed/core";
+const Positive = Schema.Int.check(Schema.isBetween({ minimum: 1, maximum: Number.MAX_SAFE_INTEGER })), Count = Schema.Int.check(Schema.isBetween({ minimum: 0, maximum: Number.MAX_SAFE_INTEGER }));
+export const ProcessHostConfig = Schema.Struct({
+  owners: Schema.Array(Schema.Trimmed.check(Schema.isNonEmpty())).check(Schema.isMinLength(1), Schema.isMaxLength(1000)),
+  events: ProcessEventMode,
+  maxBegins: Positive.check(Schema.isLessThanOrEqualTo(64)),
+  maxShortCommands: Positive.check(Schema.isLessThanOrEqualTo(256)),
+  controlCapacity: Positive.check(Schema.isLessThanOrEqualTo(64)),
+  handshakeTimeoutMs: Positive,
+  shutdown: Schema.Struct({ deadlineMs: Count, reserveMs: Count }).check(Schema.makeFilter((value) => value.reserveMs <= value.deadlineMs || "shutdown reserve must not exceed the deadline"))
+}), processHostDefaults = {
+  events: "projection",
+  maxBegins: 8,
+  maxShortCommands: 32,
+  controlCapacity: 8,
+  handshakeTimeoutMs: 1e4,
+  shutdown: { deadlineMs: 25000, reserveMs: 2000 }
+};
+
+export class ProcessHostError extends Schema.TaggedError()("ProcessHostError", {
+  reason: Schema.Literals(["Config", "Protocol", "Setup", "Peer", "Runtime"]),
+  code: ProcessErrorCode,
+  message: Schema.String,
+  cause: Schema.optional(Schema.Defect())
+}) {
+}
+export const ProcessActiveRequest = Schema.Struct({
+  requestId: ProcessRequestId,
+  lane: Schema.Literals(["begin", "short", "control"]),
+  begin: Schema.OptionFromNullOr(Schema.Struct({ session: SessionAddress, runId: RunId, turn: Schema.OptionFromNullOr(Positive) }))
+}), ProcessDispatchState = Schema.Union([
+  Schema.TaggedStruct("AwaitingHello", { requests: Schema.Array(ProcessActiveRequest) }),
+  Schema.TaggedStruct("Starting", { requests: Schema.Array(ProcessActiveRequest) }),
+  Schema.TaggedStruct("Open", { requests: Schema.Array(ProcessActiveRequest) }),
+  Schema.TaggedStruct("Stopping", { requests: Schema.Array(ProcessActiveRequest) })
+]).pipe(Schema.toTaggedUnion("_tag"));

package/dist/process-peer.conformance.d.ts

@@ -0,0 +1,27 @@
+import { Effect } from "effect";
+import type { Context, Scope } from "effect";
+import type { ConformanceCheck } from "@xandreed/core/conformance";
+import type { ProcessPeer } from "./ports/process-peer.port.js";
+import type { ProcessPeerOptions } from "./process-peer.entity.js";
+/** Native-driver controls used to run the peer contract against an adapter. @public */
+export interface ProcessPeerFixture {
+    readonly peer: Context.Service.Shape<typeof ProcessPeer>;
+    readonly feed: (bytes: Uint8Array) => Effect.Effect<void>;
+    readonly finishInput: Effect.Effect<void>;
+    readonly writes: Effect.Effect<ReadonlyArray<Uint8Array>>;
+    readonly releaseWrites: Effect.Effect<void>;
+    readonly failOutput: Effect.Effect<void>;
+}
+/** Opens a fresh scoped peer; held writes withhold their native acknowledgement. @public */
+export interface ProcessPeerSubject {
+    readonly open: (options?: Partial<ProcessPeerOptions> & {
+        readonly holdWrites?: boolean;
+    }) => Effect.Effect<ProcessPeerFixture, unknown, Scope.Scope>;
+}
+/**
+ * Checks: split-crlf, invalid-frame, invalid-utf8, unterminated, frame-bound,
+ * single-consumer, ordered-output, flush-barrier, writer-capacity, failure-latch.
+ * Each check opens a fresh peer; test drivers control input and native write ACKs.
+ * @public
+ */
+export declare const processPeerConformance: (subject: ProcessPeerSubject) => ReadonlyArray<ConformanceCheck>;

package/dist/process-peer.conformance.js

@@ -0,0 +1,99 @@
+import { Effect, Fiber, Option, Result, Stream } from "effect";
+import { check, ConformanceFailure } from "@xandreed/core/conformance";
+import { ProcessRequestId } from "./process-protocol.entity.js";
+const bytes = (text) => new TextEncoder().encode(text), hello = (id = "one") => ({ _tag: "hello", requestId: ProcessRequestId.make(id), protocolVersion: 1 }), expect = (id, holds, message) => holds ? Effect.void : Effect.fail(new ConformanceFailure({ check: id, message })), eventually = (read, holds, tries = 200) => read.pipe(Effect.flatMap((value) => holds(value) || tries <= 0 ? Effect.succeed(value) : Effect.yieldNow.pipe(Effect.andThen(Effect.suspend(() => eventually(read, holds, tries - 1)))))), outputText = (chunks) => chunks.map((chunk) => new TextDecoder().decode(chunk)).join("");
+export const processPeerConformance = (subject) => [
+  check("reads split UTF-8 commands and CRLF without losing subsequent frames", "split-crlf", () => Effect.scoped(Effect.gen(function* () {
+    const fixture = yield* subject.open({ readChunkBytes: 3 }), collected = yield* Stream.runCollect(fixture.peer.commands).pipe(Effect.forkScoped);
+    yield* fixture.feed(bytes('{"_tag":"hello","requestId":"first","protocolVersion":1}\r'));
+    yield* fixture.feed(bytes(`
+{"_tag":"ping","requestId":"second"}
+`));
+    yield* fixture.finishInput;
+    const commands = yield* Fiber.join(collected);
+    yield* expect("split-crlf", commands.length === 2 && commands[0]?._tag === "hello" && commands[1]?.requestId === "second", "split commands must arrive in order");
+  }))),
+  check("rejects a blank command frame", "invalid-frame", () => Effect.scoped(Effect.gen(function* () {
+    const fixture = yield* subject.open();
+    yield* fixture.feed(bytes(`
+`));
+    yield* fixture.finishInput;
+    const result = yield* Effect.result(Stream.runDrain(fixture.peer.commands));
+    yield* expect("invalid-frame", Result.isFailure(result) && result.failure.reason === "InvalidFrame", "blank input must fail with InvalidFrame");
+  }))),
+  check("rejects malformed UTF-8", "invalid-utf8", () => Effect.scoped(Effect.gen(function* () {
+    const fixture = yield* subject.open();
+    yield* fixture.feed(new Uint8Array([195, 40, 10]));
+    yield* fixture.finishInput;
+    const result = yield* Effect.result(Stream.runDrain(fixture.peer.commands));
+    yield* expect("invalid-utf8", Result.isFailure(result) && result.failure.reason === "InvalidUtf8", "invalid bytes must fail with InvalidUtf8");
+  }))),
+  check("rejects an unterminated final frame", "unterminated", () => Effect.scoped(Effect.gen(function* () {
+    const fixture = yield* subject.open();
+    yield* fixture.feed(bytes('{"_tag":"ping","requestId":"one"}'));
+    yield* fixture.finishInput;
+    const result = yield* Effect.result(Stream.runDrain(fixture.peer.commands));
+    yield* expect("unterminated", Result.isFailure(result) && result.failure.reason === "InvalidFrame", "EOF must not silently commit a partial frame");
+  }))),
+  check("bounds partial input frames", "frame-bound", () => Effect.scoped(Effect.gen(function* () {
+    const fixture = yield* subject.open({ maxFrameBytes: 8, readChunkBytes: 3 });
+    yield* fixture.feed(bytes(`123456789
+`));
+    yield* fixture.finishInput;
+    const result = yield* Effect.result(Stream.runDrain(fixture.peer.commands));
+    yield* expect("frame-bound", Result.isFailure(result) && result.failure.reason === "FrameTooLarge", "oversized input must fail before decoding");
+  }))),
+  check("permits only one lifetime command consumer", "single-consumer", () => Effect.scoped(Effect.gen(function* () {
+    const fixture = yield* subject.open();
+    yield* fixture.finishInput;
+    yield* Stream.runDrain(fixture.peer.commands);
+    const result = yield* Effect.result(Stream.runDrain(fixture.peer.commands));
+    yield* expect("single-consumer", Result.isFailure(result) && result.failure.reason === "Closed", "a second consumer must be rejected");
+  }))),
+  check("writes complete ordered LF-delimited frames", "ordered-output", () => Effect.scoped(Effect.gen(function* () {
+    const fixture = yield* subject.open();
+    yield* fixture.peer.send(hello("one"));
+    yield* fixture.peer.send(hello("two"));
+    yield* fixture.peer.flush;
+    const text = outputText(yield* fixture.writes);
+    yield* expect("ordered-output", text === `{"_tag":"hello","requestId":"one","protocolVersion":1}
+{"_tag":"hello","requestId":"two","protocolVersion":1}
+`, "output must contain exactly two ordered complete frames");
+  }))),
+  check("flush awaits every accepted write acknowledgement", "flush-barrier", () => Effect.scoped(Effect.gen(function* () {
+    const fixture = yield* subject.open({ holdWrites: !0 }), send = yield* fixture.peer.send(hello()).pipe(Effect.forkScoped), writes = yield* eventually(fixture.writes, (chunks) => chunks.length > 0);
+    yield* expect("flush-barrier", writes.length === 1, "the accepted write must reach the native writer");
+    const flush = yield* fixture.peer.flush.pipe(Effect.forkScoped);
+    yield* Effect.yieldNow;
+    yield* expect("flush-barrier", flush.pollUnsafe() === void 0 && send.pollUnsafe() === void 0, "neither send nor flush may complete before the native ACK");
+    yield* fixture.releaseWrites;
+    yield* Fiber.join(send);
+    yield* Fiber.join(flush);
+  }))),
+  check("makes an excess writer wait for a bounded slot, before encoding, for at most the write timeout", "writer-capacity", () => Effect.scoped(Effect.gen(function* () {
+    const fixture = yield* subject.open({ holdWrites: !0, maxPendingWrites: 1, writeTimeoutMs: 60000 }), first = yield* fixture.peer.send(hello("one")).pipe(Effect.forkScoped), writes = yield* eventually(fixture.writes, (chunks) => chunks.length > 0);
+    yield* expect("writer-capacity", writes.length === 1, "the first write must occupy the bounded slot");
+    const second = yield* Effect.result(fixture.peer.send(hello("two"))).pipe(Effect.forkScoped);
+    yield* Effect.forEach(Array.from({ length: 20 }), () => Effect.yieldNow, { concurrency: 1, discard: !0 });
+    yield* expect("writer-capacity", second.pollUnsafe() === void 0 && (yield* fixture.writes).length === 1, "an excess writer must wait for a free slot without failing or writing");
+    yield* fixture.releaseWrites;
+    yield* Fiber.join(first);
+    const waited = yield* Fiber.join(second);
+    yield* fixture.peer.flush;
+    yield* expect("writer-capacity", Result.isSuccess(waited) && outputText(yield* fixture.writes) === `{"_tag":"hello","requestId":"one","protocolVersion":1}
+{"_tag":"hello","requestId":"two","protocolVersion":1}
+`, "the waiting writer must be written once a slot frees");
+    const stalled = yield* subject.open({ holdWrites: !0, maxPendingWrites: 1, writeTimeoutMs: 20 }), held = yield* Effect.result(stalled.peer.send(hello("held"))).pipe(Effect.forkScoped);
+    yield* eventually(stalled.writes, (chunks) => chunks.length > 0);
+    const bounded = yield* Effect.result(stalled.peer.send(hello("bounded"))).pipe(Effect.timeoutOption(5000));
+    yield* Fiber.join(held);
+    yield* expect("writer-capacity", Option.exists(bounded, (result) => Result.isFailure(result) && ["Capacity", "WriteTimeout"].includes(result.failure.reason)), "a writer waiting on a stalled output must fail within the write timeout");
+  }))),
+  check("preserves the first output failure for flush and later sends", "failure-latch", () => Effect.scoped(Effect.gen(function* () {
+    const fixture = yield* subject.open({ holdWrites: !0 }), send = yield* Effect.result(fixture.peer.send(hello())).pipe(Effect.forkScoped), writes = yield* eventually(fixture.writes, (chunks) => chunks.length > 0);
+    yield* expect("failure-latch", writes.length === 1, "the write must be accepted before failing output");
+    yield* fixture.failOutput;
+    const first = yield* Fiber.join(send), flushed = yield* Effect.result(fixture.peer.flush), later = yield* Effect.result(fixture.peer.send(hello("later")));
+    yield* expect("failure-latch", Result.isFailure(first) && Result.isFailure(flushed) && Result.isFailure(later) && first.failure.reason === flushed.failure.reason && first.failure.reason === later.failure.reason, "output failure must remain observable after pending writers settle");
+  })))
+];