@phreshos/node 0.1.12 → 0.1.13

package/dist/shell.js

@@ -0,0 +1,125 @@
+import { spawn } from "node:child_process";
+import { homedir } from "node:os";
+import ProcessTree from "./process-tree.js";
+/** Execute one command locally while its iterator owns the complete process tree. */
+export default function shell(command, options = {}) {
+    return (async function* () {
+        const input = validate(command, options);
+        const queue = [];
+        let wake = null;
+        let failure = null;
+        let closed = false;
+        let treeEnded = false;
+        let ending = null;
+        let settle;
+        const stopped = new Promise(resolve => { settle = resolve; });
+        const notify = () => {
+            wake?.();
+            wake = null;
+        };
+        const finish = () => {
+            if (!closed || !treeEnded || !ending)
+                return;
+            queue.push({
+                event: {
+                    event: "exited",
+                    exit: {
+                        status: ending.signal ? "signaled" : "exited",
+                        code: ending.code,
+                        signal: ending.signal
+                    }
+                }
+            });
+            settle();
+            notify();
+        };
+        const child = spawn(input.command, {
+            shell: true,
+            detached: true,
+            cwd: input.cwd,
+            env: { ...process.env, ...input.env },
+            stdio: ["ignore", "pipe", "pipe"]
+        });
+        const tree = new ProcessTree(child, (code, signal) => {
+            ending = { code, signal };
+            treeEnded = true;
+            finish();
+        });
+        const output = (stream, name) => {
+            stream.on("data", chunk => {
+                stream.pause();
+                queue.push({ event: { event: "output", stream: name, text: String(chunk) }, resume: () => stream.resume() });
+                notify();
+            });
+        };
+        const abort = () => {
+            failure = options.signal?.reason instanceof Error ? options.signal.reason : new Error("The shell command was cancelled");
+            tree.stop();
+            notify();
+        };
+        child.once("spawn", () => {
+            if (typeof child.pid !== "number") {
+                failure = new Error("The shell command started without a process identity");
+                tree.stop();
+            }
+            else {
+                queue.push({ event: { event: "started", pid: child.pid } });
+            }
+            notify();
+        });
+        child.once("error", error => {
+            failure = error;
+            settle();
+            notify();
+        });
+        child.once("close", () => {
+            closed = true;
+            finish();
+        });
+        output(child.stdout, "stdout");
+        output(child.stderr, "stderr");
+        if (options.signal?.aborted)
+            abort();
+        else
+            options.signal?.addEventListener("abort", abort, { once: true });
+        try {
+            while (true) {
+                if (failure)
+                    throw failure;
+                const next = queue.shift();
+                if (next) {
+                    yield next.event;
+                    next.resume?.();
+                    if (next.event.event === "exited")
+                        return;
+                    continue;
+                }
+                await new Promise(resolve => { wake = resolve; });
+            }
+        }
+        finally {
+            options.signal?.removeEventListener("abort", abort);
+            if (!closed || !treeEnded)
+                tree.stop();
+            await stopped;
+        }
+    })();
+}
+function validate(command, options) {
+    if (typeof command !== "string" || !command.trim())
+        throw new Error("A shell command must be non-empty text");
+    if (!options || typeof options !== "object" || Array.isArray(options))
+        throw new Error("Shell options must be an object");
+    if (Object.keys(options).some(key => key !== "cwd" && key !== "env" && key !== "signal"))
+        throw new Error("Shell options contain an unknown field");
+    if (options.signal !== undefined && !(options.signal instanceof AbortSignal))
+        throw new Error("A shell signal must be an AbortSignal");
+    const cwd = options.cwd ?? homedir();
+    const env = options.env ?? {};
+    if (typeof cwd !== "string" || !cwd)
+        throw new Error("A shell working directory must be non-empty text");
+    if (!env || typeof env !== "object" || Array.isArray(env) || Object.values(env).some(value => typeof value !== "string")) {
+        throw new Error("Shell environment values must be text");
+    }
+    return { command, cwd, env };
+}

package/dist/storage.d.ts

@@ -1,3 +1,7 @@
-import type { SystemStorage } from "@phreshos/core";
+import type { Storage } from "@phreshos/core";
 /** Create one filesystem implementation bounded beneath a resolved absolute root. */
-export declare function filesystemStorage(source: string | (() => Promise<string>), label: string): SystemStorage;
+export declare function filesystemStorage(source: string | (() => Promise<string>), label: string, lifetime?: Lifetime): Storage;
+/** Create native filesystem access entered from one resolved absolute path. */
+export declare function nativeStorage(source: string | (() => Promise<string>), label: string, lifetime?: Lifetime): Storage;
+type Lifetime = () => AbortSignal;
+export {};

package/dist/storage.js

@@ -1,39 +1,51 @@
 import { randomUUID } from "node:crypto";
 import { createReadStream, createWriteStream, lstatSync, mkdirSync, readdirSync, renameSync, rmSync, statSync } from "node:fs";
 import { rm } from "node:fs/promises";
-import { dirname, isAbsolute, join, relative, sep } from "node:path";
+import { dirname, isAbsolute, join, relative, resolve as resolvePath, sep } from "node:path";
 import { Readable } from "node:stream";
 import { pipeline } from "node:stream/promises";
 /** Create one filesystem implementation bounded beneath a resolved absolute root. */
-export function filesystemStorage(source, label) {
+export function filesystemStorage(source, label, lifetime) {
+    return createStorage(source, label, contained, lifetime);
+}
+/** Create native filesystem access entered from one resolved absolute path. */
+export function nativeStorage(source, label, lifetime) {
+    return createStorage(source, label, (root, parts) => resolvePath(root, ...parts), lifetime);
+}
+function createStorage(source, label, locate, lifetime) {
     let root = null;
     const resolveRoot = () => {
+        active(lifetime);
         if (!root)
             root = Promise.resolve(typeof source === "string" ? source : source()).then(value => {
+                active(lifetime);
                 if (!isAbsolute(value))
                     throw new Error("A Storage root must be absolute");
                 return value;
             });
         return root;
     };
-    const path = () => resolveRoot();
-    const resolve = async (...parts) => contained(await path(), parts);
+    const path = async () => await resolveRoot();
+    const resolve = async (...parts) => locate(await path(), parts);
     async function stream(...parts) {
+        const signal = active(lifetime);
         const destination = await resolve(...parts);
         const found = describe(destination);
         if (!found)
             throw new Error(`There is no ${parts.join("/")} in ${label}`);
         if (found.kind !== "file")
             throw new Error(`${parts.join("/")} is not a file`);
-        return Readable.toWeb(createReadStream(destination));
+        return Readable.toWeb(createReadStream(destination, { signal }));
     }
     async function write(...args) {
+        const signal = active(lifetime);
         const parts = args.slice(0, -1);
         const destination = await resolve(...parts);
         const temporary = join(dirname(destination), `.${randomUUID()}.writing`);
         mkdirSync(dirname(destination), { recursive: true });
         try {
-            await pipeline(Readable.fromWeb(content(args.at(-1))), createWriteStream(temporary, { flags: "wx" }));
+            await pipeline(Readable.fromWeb(content(args.at(-1))), createWriteStream(temporary, { flags: "wx" }), { signal });
+            signal?.throwIfAborted();
             renameSync(temporary, destination);
         }
         catch (error) {
@@ -49,14 +61,16 @@ export function filesystemStorage(source, label) {
         async text(...parts) { return new Response(await stream(...parts)).text(); },
         async json(...parts) { return JSON.parse(await new Response(await stream(...parts)).text()); },
         write,
-        async stat(...parts) { return describe(await resolve(...parts)); },
-        async list(...parts) { return readdirSync(await resolve(...parts)).sort(); },
+        async stat(...parts) { active(lifetime); return describe(await resolve(...parts)); },
+        async list(...parts) { active(lifetime); return readdirSync(await resolve(...parts)).sort(); },
         async delete(...parts) {
+            active(lifetime);
             if (!parts.length)
                 throw new Error("Emptying a place is clear, not delete");
             rmSync(await resolve(...parts), { recursive: true, force: true });
         },
         async clear(...parts) {
+            active(lifetime);
             const destination = await resolve(...parts);
             const found = describe(destination);
             if (found && found.kind !== "directory")
@@ -66,6 +80,11 @@ export function filesystemStorage(source, label) {
         }
     };
 }
+function active(lifetime) {
+    const signal = lifetime?.();
+    signal?.throwIfAborted();
+    return signal;
+}
 function content(value) {
     if (value instanceof ReadableStream)
         return value;

package/dist/system.d.ts

@@ -1,42 +1,47 @@
-import { Client as CoreClient, ClientService as CoreClientService, Endpoint as CoreEndpoint, Process as CoreProcess, Program as CoreProgram, Server as CoreServer, ServerService as CoreServerService, type ProgramDefinition, type ServiceKey, type System as CoreSystem, type SystemClientEntity, type SystemEndpointEntity, type SystemProcessEntity, type SystemProcess, type SystemProcessRunEvent, type SystemProcessRunOptions, type SystemProgram, type SystemProgramEntity, type SystemServerEntity, type SystemUploads, type SystemStorage, type WritableAppearance } from "@phreshos/core";
-export type ProgramProcessRunOptions = SystemProcessRunOptions;
-export type ProgramProcessRunEvent = SystemProcessRunEvent;
+import { ClientEndpoint as CoreClientEndpoint, ClientService as CoreClientService, Endpoint as CoreEndpoint, Process as CoreProcess, Program as CoreProgram, ServerEndpoint as CoreServerEndpoint, ServerService as CoreServerService, type ProgramDefinition, type ProgramProcessRunEvent as CoreProgramProcessRunEvent, type ProgramProcessRunOptions as CoreProgramProcessRunOptions, type ServiceKey, type ShellOptions, type System as CoreSystem, type SystemProcess, type SystemProgram, type SystemUploads, type Storage, type WritableAppearance } from "@phreshos/core";
+export type ProgramProcessRunOptions = CoreProgramProcessRunOptions;
+export type ProgramProcessRunEvent = CoreProgramProcessRunEvent;
+type ServiceEndpoint = ServiceKey["endpoint"];
+type ServiceAddress<Endpoint extends ServiceEndpoint> = Omit<ServiceKey, "endpoint"> & Readonly<{
+    endpoint: Endpoint;
+}>;
+type ServiceHandle<Endpoint extends ServiceEndpoint, EventsMap extends object, Fallback = unknown> = Endpoint extends "server" ? ServerService<EventsMap, Fallback> : ClientService<EventsMap, Fallback>;
 /** One connected owner-local implementation of the shared System contract. */
 export declare class System implements CoreSystem {
-    readonly storage: SystemStorage;
+    readonly storage: Storage;
     readonly appearance: WritableAppearance;
     readonly program: SystemProgram;
     readonly process: SystemProcess;
     readonly uploads: SystemUploads;
+    fetch(input: RequestInfo | URL, init?: RequestInit): Promise<Response>;
+    shell(command: string, options?: ShellOptions): AsyncGenerator<import("@phreshos/core").ShellEvent, void, void>;
     private constructor();
     /** Connect to the System selected by argument, environment, or owner default. */
     static connect(home?: string): Promise<System>;
     /** Atomically replace one runtime Program without touching its installed form. */
-    forceCreateProgram(source: ProgramDefinition | string): Promise<SystemProgramEntity>;
+    forceCreateProgram(source: ProgramDefinition | string): Promise<Program>;
     /** Close this owner connection and abort every attached operation it owns. */
     disconnect(): Promise<void>;
-    service<EventsMap extends object = {}, Fallback = unknown>(key: ServiceKey & {
-        endpoint: "server";
-    }): ServerService<EventsMap, Fallback>;
-    service<EventsMap extends object = {}, Fallback = unknown>(key: ServiceKey & {
-        endpoint: "client";
-    }): ClientService<EventsMap, Fallback>;
+    service<Endpoint extends ServiceEndpoint>(key: ServiceAddress<Endpoint>): ServiceHandle<Endpoint, {}>;
+    service<EventsMap extends object = {}, Fallback = unknown>(key: ServiceAddress<"server">): ServerService<EventsMap, Fallback>;
+    service<EventsMap extends object = {}, Fallback = unknown>(key: ServiceAddress<"client">): ClientService<EventsMap, Fallback>;
 }
-/** Node-SDK handle for a Service provided by a Server Endpoint. */
+/** Node SDK handle for a Service provided by a Server Endpoint. */
 export declare class ServerService<EventsMap extends object = {}, Fallback = unknown> extends CoreServerService<EventsMap, Fallback> {
     protected constructor();
 }
-/** Node-SDK handle for a Service provided by a Client Endpoint. */
+/** Node SDK handle for a Service provided by a Client Endpoint. */
 export declare class ClientService<EventsMap extends object = {}, Fallback = unknown> extends CoreClientService<EventsMap, Fallback> {
     protected constructor();
 }
-export type Program = SystemProgramEntity;
+export type Program = CoreProgram;
 export declare const Program: typeof CoreProgram;
-export type Process = SystemProcessEntity;
+export type Process = CoreProcess;
 export declare const Process: typeof CoreProcess;
-export type Endpoint<EventsMap extends object = {}, Fallback = unknown> = SystemEndpointEntity<EventsMap, Fallback>;
+export type Endpoint<EventsMap extends object = {}, Fallback = unknown> = CoreEndpoint<EventsMap, Fallback>;
 export declare const Endpoint: typeof CoreEndpoint;
-export type Server<EventsMap extends object = {}, Fallback = unknown> = SystemServerEntity<EventsMap, Fallback>;
-export declare const Server: typeof CoreServer;
-export type Client<EventsMap extends object = {}, Fallback = unknown> = SystemClientEntity<EventsMap, Fallback>;
-export declare const Client: typeof CoreClient;
+export type ServerEndpoint<EventsMap extends object = {}, Fallback = unknown> = CoreServerEndpoint<EventsMap, Fallback>;
+export declare const ServerEndpoint: typeof CoreServerEndpoint;
+export type ClientEndpoint<EventsMap extends object = {}, Fallback = unknown> = CoreClientEndpoint<EventsMap, Fallback>;
+export declare const ClientEndpoint: typeof CoreClientEndpoint;
+export {};

package/dist/system.js

@@ -1,39 +1,49 @@
-import { Client as CoreClient, ClientService as CoreClientService, Endpoint as CoreEndpoint, Process as CoreProcess, Program as CoreProgram, Server as CoreServer, ServerService as CoreServerService, isServiceKey } from "@phreshos/core";
+import { ClientEndpoint as CoreClientEndpoint, ClientService as CoreClientService, Endpoint as CoreEndpoint, Process as CoreProcess, Program as CoreProgram, ServerEndpoint as CoreServerEndpoint, ServerService as CoreServerService, isServiceKey } from "@phreshos/core";
 import { homedir } from "node:os";
 import { gatewayAddress } from "./address.js";
 import Events from "./events.js";
 import HandleRegistry from "./handle-registry.js";
 import { resolveHome } from "./home.js";
-import { filesystemStorage } from "./storage.js";
-import { programPermission, programSql, programStore } from "./program-resources.js";
+import { filesystemStorage, nativeStorage } from "./storage.js";
+import { programPermissions, programSql, programStore } from "./program-resources.js";
 import { EndpointTrafficHandle, ServerTrafficHandle } from "./traffic.js";
-import { openConnection, request, streamProgram } from "./transport.js";
+import { openConnection, request, stream } from "./transport.js";
 import Uploads from "./uploads.js";
+import shell from "./shell.js";
 const systems = new WeakMap();
 const ProgramBase = CoreProgram;
 const ProcessBase = CoreProcess;
-const ServerBase = CoreServer;
-const ClientBase = CoreClient;
+const ServerEndpointBase = CoreServerEndpoint;
+const ClientEndpointBase = CoreClientEndpoint;
 /** One connected owner-local implementation of the shared System contract. */
 export class System {
-    storage = filesystemStorage(homedir(), "the native home directory");
+    storage;
     appearance;
     program;
     process;
     uploads;
+    async fetch(input, init) {
+        const request = new Request(input, init);
+        return await fetch(request, { signal: connectedSignal(this, request.signal) });
+    }
+    async *shell(command, options = {}) {
+        yield* shell(command, { ...options, signal: connectedSignal(this, options.signal) });
+    }
     constructor(address, connection) {
         const lifetime = new AbortController();
         const handles = new HandleRegistry();
         const transport = {
             control: (value, signal) => request(address, "system", value, connectedSignal(this, signal)),
             api: (value, signal) => request(address, "api", value, connectedSignal(this, signal)),
-            lifecycle: (value, signal) => streamProgram(address, value, connectedSignal(this, signal))
+            stream: (target, value, signal) => stream(address, target, value, connectedSignal(this, signal))
         };
         systems.set(this, { address, connection, handles, lifetime, transport, closed: false });
+        connection.once("close", () => closeSystem(this, new Error("This System connection is closed")));
+        this.storage = nativeStorage(homedir(), "the native filesystem", () => connectedSignal(this));
         this.appearance = new SystemAppearance(transport);
         this.program = new ProgramRegistry(this);
         this.process = new ProcessRegistry(this);
-        this.uploads = new Uploads(value => transport.api(value));
+        this.uploads = new Uploads(value => transport.api(value), () => connectedSignal(this));
     }
     /** Connect to the System selected by argument, environment, or owner default. */
     static async connect(home) {
@@ -44,7 +54,7 @@ export class System {
     /** Atomically replace one runtime Program without touching its installed form. */
     async forceCreateProgram(source) {
         requireConnected(this);
-        for await (const event of transport(this).lifecycle({ word: "force-create", program: source })) {
+        for await (const event of transport(this).stream("program", { word: "force-create", program: source })) {
             if (event.event === "created")
                 return programHandle(this, required(event.program));
         }
@@ -52,13 +62,7 @@ export class System {
     }
     /** Close this owner connection and abort every attached operation it owns. */
     async disconnect() {
-        const state = systemState(this);
-        if (state.closed)
-            return;
-        state.closed = true;
-        state.lifetime.abort(new Error("This System connection is closed"));
-        state.connection.destroy();
-        state.handles.clear();
+        closeSystem(this, new Error("This System connection is closed"));
     }
     service(key) {
         requireConnected(this);
@@ -81,6 +85,15 @@ function systemState(system) {
         throw new Error("Unknown System connection");
     return state;
 }
+function closeSystem(system, reason) {
+    const state = systemState(system);
+    if (state.closed)
+        return;
+    state.closed = true;
+    state.lifetime.abort(reason);
+    state.connection.destroy();
+    state.handles.clear();
+}
 function requireConnected(system) {
     if (systemState(system).closed)
         throw new Error("This System connection is closed");
@@ -149,7 +162,7 @@ class ProgramRegistry extends Events {
         }
     }
     async create(source) {
-        for await (const event of transport(this.system).lifecycle({ word: "create", program: source })) {
+        for await (const event of transport(this.system).stream("program", { word: "create", program: source })) {
             if (event.event === "created")
                 return programHandle(this.system, required(event.program));
         }
@@ -173,9 +186,9 @@ class ProgramHandle extends ProgramBase {
     store;
     logs;
     database;
-    permission;
     process;
     startup;
+    permissions;
     snapshot;
     constructor(system, snapshot) {
         super();
@@ -188,16 +201,17 @@ class ProgramHandle extends ProgramBase {
             capability: "program", operation: "wait", handle: address, event, timeout
         }, signal)));
         const request = (value) => transport(system).api(value);
-        this.data = filesystemStorage(() => programStoragePath(system, address, "data"), `Program "${this.identity}" data`);
-        this.cache = filesystemStorage(() => programStoragePath(system, address, "cache"), `Program "${this.identity}" cache`);
+        this.data = filesystemStorage(() => programStoragePath(system, address, "data"), `Program "${this.identity}" data`, () => connectedSignal(system));
+        this.cache = filesystemStorage(() => programStoragePath(system, address, "cache"), `Program "${this.identity}" cache`, () => connectedSignal(system));
         this.store = programStore(request, address);
         this.logs = programSql(request, address, "logs");
         this.database = programSql(request, address, "database");
-        this.permission = programPermission(request, address);
         this.process = new ProgramProcesses(system, this);
         this.startup = new ProgramStartup(system, this);
+        this.permissions = programPermissions(request, address);
     }
     get name() { return this.snapshot.name; }
+    get assetId() { return this.snapshot.assetId; }
     get version() { return this.snapshot.version; }
     get description() { return this.snapshot.description; }
     get hasAgent() { return this.snapshot.hasAgent; }
@@ -215,7 +229,8 @@ class ProgramHandle extends ProgramBase {
             size: this.snapshot.client.size,
             position: this.snapshot.client.position,
             layer: this.snapshot.client.layer,
-            minimize: this.snapshot.client.minimize
+            minimize: this.snapshot.client.minimize,
+            permissions: Object.freeze(Object.fromEntries(Object.entries(this.snapshot.client.permissions).map(([name, values]) => [name, Object.freeze([...values])])))
         }) : null;
     }
     update(snapshot) {
@@ -236,7 +251,7 @@ class ProgramHandle extends ProgramBase {
         return typeof value === "string" ? value : null;
     }
     async installed() {
-        for await (const event of transport(this.system).lifecycle({ word: "installed", handle: this.address() })) {
+        for await (const event of transport(this.system).stream("program", { word: "installed", handle: this.address() })) {
             if (event.event === "installedState")
                 return event.installed === true;
         }
@@ -245,14 +260,14 @@ class ProgramHandle extends ProgramBase {
     install() { return command(this.system, { word: "install-existing", handle: this.address() }); }
     uninstall(everything = false) { return command(this.system, { word: "uninstall-existing", handle: this.address(), everything }); }
     async fork(identity) {
-        for await (const event of transport(this.system).lifecycle({ word: "fork", handle: this.address(), identity })) {
+        for await (const event of transport(this.system).stream("program", { word: "fork", handle: this.address(), identity })) {
             if (event.event === "created")
                 return programHandle(this.system, required(event.program));
         }
         throw new Error("The System did not confirm the forked Program");
     }
     async forget() {
-        for await (const _event of transport(this.system).lifecycle({ word: "forget", handle: this.address() })) { /* consume completion */ }
+        for await (const _event of transport(this.system).stream("program", { word: "forget", handle: this.address() })) { /* consume completion */ }
     }
     address() { return Object.freeze({ identity: this.identity, reference: this.reference }); }
 }
@@ -264,7 +279,7 @@ class ProgramStartup {
         this.program = program;
     }
     async get() {
-        for await (const event of transport(this.system).lifecycle({
+        for await (const event of transport(this.system).stream("program", {
             word: "startup", handle: this.program.address(), operation: "get"
         })) {
             if (event.event === "startup")
@@ -279,7 +294,7 @@ class ProgramStartup {
         await this.change("disable");
     }
     async change(operation, launch) {
-        for await (const event of transport(this.system).lifecycle({
+        for await (const event of transport(this.system).stream("program", {
             word: "startup", handle: this.program.address(), operation, launch
         })) {
             if (event.event === "startup")
@@ -313,7 +328,7 @@ class ProgramProcesses extends Events {
     create(launch = {}) { return this.createExact("create-process", launch); }
     async *run(launch = {}, options = {}) {
         let process = null;
-        for await (const event of transport(this.system).lifecycle({
+        for await (const event of transport(this.system).stream("program", {
             word: "run-process",
             handle: this.program.address(),
             launch
@@ -360,7 +375,7 @@ class ProgramProcesses extends Events {
         return processes.map(process => process.identity);
     }
     async createExact(word, launch) {
-        for await (const event of transport(this.system).lifecycle({ word, handle: this.program.address(), launch })) {
+        for await (const event of transport(this.system).stream("program", { word, handle: this.program.address(), launch })) {
             if (event.event === "createdProcess")
                 return processHandle(this.system, required(event.process));
         }
@@ -406,8 +421,8 @@ class ProcessHandle extends ProcessBase {
         this.identity = snapshot.identity;
         this.name = snapshot.name;
         this.startedAt = new Date(snapshot.startedAt);
-        this.server = new ServerEndpoint(system, this);
-        this.client = new ClientEndpoint(system, this);
+        this.server = new ServerEndpointHandle(system, this);
+        this.client = new ClientEndpointHandle(system, this);
     }
     program() { return programHandle(this.system, required(this.snapshot.programSnapshot, this.snapshot.program)); }
     async parent() {
@@ -478,7 +493,7 @@ class EndpointOperations extends Events {
             } });
     }
 }
-class ServerEndpoint extends ServerBase {
+class ServerEndpointHandle extends ServerEndpointBase {
     system;
     owner;
     endpoint = "server";
@@ -512,7 +527,7 @@ class ServerEndpoint extends ServerBase {
             }) };
     }
 }
-class ClientEndpoint extends ClientBase {
+class ClientEndpointHandle extends ClientEndpointBase {
     endpoint = "client";
     traffic;
     lifecycle;
@@ -583,7 +598,7 @@ class ServiceBase {
         void transport(this.system).api({ capability: "service", operation: "publish", key: this.key, event, payload });
     }
 }
-/** Node-SDK handle for a Service provided by a Server Endpoint. */
+/** Node SDK handle for a Service provided by a Server Endpoint. */
 export class ServerService extends CoreServerService {
     constructor() { super(); }
 }
@@ -614,7 +629,7 @@ class ServerServiceHandle extends ServerService {
             }) };
     }
 }
-/** Node-SDK handle for a Service provided by a Client Endpoint. */
+/** Node SDK handle for a Service provided by a Client Endpoint. */
 export class ClientService extends CoreClientService {
     constructor() { super(); }
 }
@@ -645,7 +660,7 @@ async function listProcesses(system) {
     }
 }
 async function* command(system, request) {
-    for await (const event of transport(system).lifecycle(request)) {
+    for await (const event of transport(system).stream("program", request)) {
         if (event.event === "output")
             yield {
                 stream: event.stream === "stderr" ? "stderr" : "stdout",
@@ -747,5 +762,5 @@ function required(value, identity = "") {
 export const Program = CoreProgram;
 export const Process = CoreProcess;
 export const Endpoint = CoreEndpoint;
-export const Server = CoreServer;
-export const Client = CoreClient;
+export const ServerEndpoint = CoreServerEndpoint;
+export const ClientEndpoint = CoreClientEndpoint;

package/dist/traffic.d.ts

@@ -15,13 +15,13 @@ export declare class EndpointTrafficHandle<Definitions extends object = {}> exte
         event: string;
         questionId: string;
         message: Readonly<{
-            to: import("@phreshos/core").Server<{}, unknown> | null;
+            to: import("@phreshos/core").ServerEndpoint<{}, unknown> | null;
             payload: Payload;
         }>;
     }>>;
     protected follow<Capture>(kind: Kind, convert: (value: unknown) => Capture, subscriber: (capture: Capture) => unknown, impossible?: (error: Error) => void): Cleanup;
 }
-/** Directed traffic originating from one canonical Server. */
+/** Directed traffic originating from one canonical Server Endpoint. */
 export declare class ServerTrafficHandle<Definitions extends object = {}> extends EndpointTrafficHandle<Definitions> implements ServerTraffic<Definitions> {
     subscribeAnswers<Result = unknown>(subscriber: AnswerSubscriber<Result>): Cleanup;
     answers<Result = unknown>(options?: EventOptions): AsyncIterableIterator<Readonly<{

package/dist/traffic.js

@@ -52,7 +52,7 @@ export class EndpointTrafficHandle extends Events {
         return () => controller.abort();
     }
 }
-/** Directed traffic originating from one canonical Server. */
+/** Directed traffic originating from one canonical Server Endpoint. */
 export class ServerTrafficHandle extends EndpointTrafficHandle {
     subscribeAnswers(subscriber) {
         return this.follow("answer", value => answer(value, this.resolveEndpoint), subscriber);

package/dist/transport.d.ts

@@ -7,5 +7,5 @@ export interface TransportEvent {
 export declare function openConnection(path: string): Promise<Socket>;
 /** Execute one short authoritative System-control request. */
 export declare function request(path: string, target: "api" | "system", request: unknown, signal?: AbortSignal): Promise<unknown>;
-/** Stream one Program lifecycle operation until the System completes it. */
-export declare function streamProgram(path: string, request: unknown, signal?: AbortSignal): AsyncGenerator<TransportEvent, void, unknown>;
+/** Stream one long-running authoritative System operation. */
+export declare function stream(path: string, target: "program", request: unknown, signal?: AbortSignal): AsyncGenerator<TransportEvent, void, unknown>;

package/dist/transport.js

@@ -1,4 +1,5 @@
 import { connect } from "node:net";
+const maximumStreamQueue = 256;
 /** Open and retain one owner-local System connection. */
 export function openConnection(path) {
     return new Promise((resolve, reject) => {
@@ -52,8 +53,8 @@ export function request(path, target, request, signal) {
             cancel();
     });
 }
-/** Stream one Program lifecycle operation until the System completes it. */
-export function streamProgram(path, request, signal) {
+/** Stream one long-running authoritative System operation. */
+export function stream(path, target, request, signal) {
     const events = [];
     let wake = null;
     let ended = false;
@@ -65,14 +66,27 @@ export function streamProgram(path, request, signal) {
     else
         signal?.addEventListener("abort", cancel, { once: true });
     let buffer = "";
-    socket.on("connect", () => socket.write(`${JSON.stringify({ target: "program", request })}\n`));
+    socket.on("connect", () => socket.write(`${JSON.stringify({ target, request })}\n`));
     socket.on("data", chunk => {
         buffer += String(chunk);
         const lines = buffer.split("\n");
         buffer = lines.pop() ?? "";
         for (const line of lines)
             if (line.trim()) {
-                const event = JSON.parse(line);
+                if (events.length >= maximumStreamQueue) {
+                    failure = new Error(`System stream queue exceeded its capacity of ${maximumStreamQueue}`);
+                    socket.destroy();
+                    break;
+                }
+                let event;
+                try {
+                    event = JSON.parse(line);
+                }
+                catch {
+                    failure = new Error("The System returned an invalid stream event");
+                    socket.destroy();
+                    break;
+                }
                 if (event.event === "error")
                     failure = new Error(String(event.message));
                 else