@phreshos/node 0.1.17 → 0.1.19

package/README.md

@@ -56,6 +56,12 @@ bun run verify
 `verify` checks the types, builds the package, runs the connection and Project
 tests, and validates the published package shape independently.
 
+`check` performs static checks, `build` creates distributable output, and `test`
+runs Vitest assertions from `tests/`. Run `build` before testing built artifacts.
+`verify` runs `check`, `build`, and `test` in order. Operational tooling belongs
+in `scripts/`; tests and their fixtures belong in `tests/`. Verification uses
+the committed dependency graph without local package substitutions.
+
 ## Related repositories
 
 - [`@phreshos/core`](https://github.com/PhreshOS/core) owns the shared System

package/dist/events.d.ts

@@ -1,14 +1,15 @@
-import type { Cleanup, EventOptions, Subscribable } from "@phreshos/core";
+import { subscribableDefinition, type Cleanup, type EventOptions, type Subscribable, type SubscribableDefinition } from "@phreshos/core";
 type Failure = (error: Error) => void;
 type Register<Message> = (subscriber: (message: Message) => unknown, impossible?: Failure) => Cleanup;
 type Subscribe = (event: string | null, subscriber: (message: unknown) => unknown, impossible?: Failure) => Cleanup;
 /** Adapts one live representation source into the shared Subscribable contract. */
-export default class Events<Definitions extends object, Fallback = never> {
+export default class Events<Definitions extends object, Fallback = never> implements Subscribable<Definitions, Fallback> {
     private readonly names;
     private readonly register;
+    readonly [subscribableDefinition]?: SubscribableDefinition<Definitions, Fallback>;
     constructor(names: readonly string[], register: Subscribe);
     readonly subscribe: Subscribable<Definitions, Fallback>["subscribe"];
-    readonly waitFor: Subscribable<Definitions, Fallback>["waitFor"];
+    readonly wait: Subscribable<Definitions, Fallback>["wait"];
     readonly events: Subscribable<Definitions, Fallback>["events"];
     private listen;
 }

package/dist/events.js

@@ -1,3 +1,4 @@
+import { subscribableDefinition } from "@phreshos/core";
 /** Adapts one live representation source into the shared Subscribable contract. */
 export default class Events {
     names;
@@ -19,7 +20,7 @@ export default class Events {
                 eventOrSubscriber({ event: capture.event, message: capture.payload });
         });
     });
-    waitFor = ((event, timeout = 10_000) => new Promise((resolve, reject) => {
+    wait = ((event, timeout = 10_000) => new Promise((resolve, reject) => {
         let stop = () => undefined;
         const timer = setTimeout(() => {
             stop();

package/dist/network.d.ts

@@ -0,0 +1,3 @@
+import type { Network } from "@phreshos/core";
+/** Networking shares the lifetime of its owning System connection. */
+export default function network(signal: () => AbortSignal): Network;

package/dist/network.js

@@ -0,0 +1,13 @@
+import websocket from "./websocket.js";
+/** Networking shares the lifetime of its owning System connection. */
+export default function network(signal) {
+    return {
+        async fetch(input, init) {
+            const request = new Request(input, init);
+            return fetch(request, { signal: AbortSignal.any([request.signal, signal()]) });
+        },
+        websocket(url, protocols) {
+            return websocket(url, protocols, signal());
+        }
+    };
+}

package/dist/project.js

@@ -1,4 +1,4 @@
-import { isRelativeValue, layers, } from "@phreshos/core";
+import { isRelativeValue, parseLaunch, layers, } from "@phreshos/core";
 import AdmZip from "adm-zip";
 import { createHash } from "node:crypto";
 import { spawn } from "node:child_process";
@@ -61,34 +61,47 @@ export class Project {
         if (mode === "development" && !config.server?.development && !config.client?.development) {
             throw new Error("Nothing here says how this Program is developed");
         }
-        return {
+        const definition = {
             identity: config.identity,
             name: config.name,
             version: config.version,
             description: config.description,
+            options: config.options,
+            startup: config.startup,
+            categories: config.categories,
+            keywords: config.keywords,
+            website: config.website,
             icon: config.icon && resolve(this.directory, config.icon),
             agent: config.agent && resolve(this.directory, config.agent),
-            storage: resolve(this.directory, "storage"),
-            ...server && { server: {
-                    location: resolve(this.directory, server.location),
-                    start: server.start,
-                    service: server.service,
-                    installCommand: config.server?.installCommand,
-                    uninstallCommand: config.server?.uninstallCommand,
-                    ...serverExecution(server)
-                } },
-            ...client && { client: {
-                    location: /^https?:\/\//i.test(client.location) ? client.location : resolve(this.directory, client.location),
-                    start: client.start,
-                    service: client.service,
-                    title: config.client?.title,
-                    size: config.client?.size,
-                    position: config.client?.position,
-                    layer: config.client?.layer,
-                    minimize: config.client?.minimize,
-                    permissions: config.client?.permissions
-                } }
+            storage: resolve(this.directory, "storage")
         };
+        const serverDefinition = server ? {
+            location: resolve(this.directory, server.location),
+            start: server.start,
+            service: server.service,
+            installCommand: config.server?.installCommand,
+            uninstallCommand: config.server?.uninstallCommand,
+            ...serverExecution(server)
+        } : null;
+        const clientDefinition = client ? {
+            location: /^https?:\/\//i.test(client.location) ? client.location : resolve(this.directory, client.location),
+            start: client.start,
+            service: client.service,
+            title: config.client?.title,
+            size: config.client?.size,
+            position: config.client?.position,
+            layer: config.client?.layer,
+            minimize: config.client?.minimize,
+            maximize: config.client?.maximize,
+            permissions: config.client?.permissions
+        } : null;
+        if (serverDefinition && clientDefinition)
+            return { ...definition, server: serverDefinition, client: clientDefinition };
+        if (serverDefinition)
+            return { ...definition, server: serverDefinition };
+        if (clientDefinition)
+            return { ...definition, client: clientDefinition };
+        throw new Error("A Program must define a Server, a Client, or both");
     }
     /** Run the optional author-owned production build command. */
     async build() {
@@ -208,6 +221,9 @@ function clientHalf(half, mode, developmentUrl) {
         : declared;
 }
 function validateConfig(config) {
+    parseLaunch({ options: config.options });
+    if (config.startup !== undefined && typeof config.startup !== "boolean")
+        parseLaunch(config.startup);
     if (typeof config.identity !== "string" || !/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(config.identity)) {
         throw new Error("A Program's identity must be kebab-case");
     }
@@ -304,6 +320,8 @@ function packageDefinition(config, version) {
         name: config.name,
         version,
         description: config.description,
+        options: config.options,
+        startup: config.startup,
         icon: config.icon ? "icon.png" : undefined,
         agent: config.agent ? "agent.md" : undefined,
         categories: config.categories,
@@ -326,6 +344,7 @@ function packageDefinition(config, version) {
                 position: config.client.position,
                 layer: config.client.layer,
                 minimize: config.client.minimize,
+                maximize: config.client.maximize,
                 permissions: config.client.permissions
             } }
     };

package/dist/representation.d.ts

@@ -1,32 +1,17 @@
-import type { Appearance, ClientDeclaration, EndpointDeclaration, ServiceKey, WindowGeometry, WindowLayer } from "@phreshos/core";
+import { type Appearance, type ProcessSnapshot, type ProgramSnapshot, type ServiceKey, type WindowState as CoreWindowState } from "@phreshos/core";
 import type { GatewayConnection } from "./transport.js";
-export interface ProgramState {
-    reference: string;
-    identity: string;
-    assetId: string;
+export type ProgramState = ProgramSnapshot & Readonly<{
     installed: boolean;
-    name: string;
-    version: string | null;
-    description: string | null;
-    hasAgent: boolean;
-    server: EndpointDeclaration | null;
-    client: ClientDeclaration | null;
-}
-export interface WindowState {
-    title: string;
-    position: WindowGeometry["position"];
-    size: WindowGeometry["size"];
+}>;
+export type WindowState = Omit<CoreWindowState, "front"> & Readonly<{
     depth: number;
-    minimized: boolean;
-    layer: WindowLayer;
-    location: string;
-}
+}>;
 export interface ProcessIdentityState {
     reference: string;
     identity: string;
     name: string | null;
     program: string;
-    options: Record<string, string>;
+    options: ProcessSnapshot["options"];
     startedAt: Date;
 }
 export interface ProcessState extends ProcessIdentityState {

package/dist/representation.js

@@ -1,4 +1,5 @@
 import { randomUUID } from "node:crypto";
+import { parseProgramSnapshot, parseAppearance } from "@phreshos/core";
 const maximumStreamQueue = 256;
 /** A connection-owned, live representation of the authoritative System model. */
 export default class SystemRepresentation {
@@ -13,7 +14,7 @@ export default class SystemRepresentation {
         this.connection = connection;
         const session = ownerSession(connection.session);
         this.authorization = session.authorization;
-        this.appearance = session.linkManager.appearance.value;
+        this.appearance = parseAppearance(session.linkManager.appearance.value);
         for (const [, value] of session.authManager.programManager.programs) {
             const program = programState(value);
             this.programs.set(program.identity, program);
@@ -133,7 +134,7 @@ export default class SystemRepresentation {
     followModel(appearance) {
         const subscribe = (event, listener) => this.release.push(this.connection.subscribe(event, listener));
         subscribe(`property-update:${appearance}`, value => {
-            this.appearance = value;
+            this.appearance = parseAppearance(value);
             this.emit("appearance", this.appearance);
         });
         subscribe("/auth/program/create", value => this.arriveProgram("create", value));
@@ -148,7 +149,7 @@ export default class SystemRepresentation {
         subscribe("/auth/process/client-stop", (identity, value) => this.changeEndpoint(identity, "client", value, false));
         subscribe("/auth/process/client-access", (identity, value) => this.changeEndpoint(identity, "client", value));
         subscribe("/auth/process/exited", (value, code, signal) => this.exitProcess(value, code, signal));
-        for (const event of ["move", "resize", "geometry", "change-title", "raise", "minimize"]) {
+        for (const event of ["move", "resize", "geometry", "change-title", "raise", "minimize", "maximize"]) {
             subscribe(`/auth/process/${event}`, value => this.changeWindow(event, value));
         }
     }
@@ -253,21 +254,10 @@ function ownerSession(value) {
     };
 }
 function programState(value) {
-    if (!record(value) || typeof value.reference !== "string" || typeof value.identity !== "string" || typeof value.assetId !== "string" || typeof value.name !== "string") {
-        throw new Error("The System returned an invalid Program");
-    }
-    return {
-        reference: value.reference,
-        identity: value.identity,
-        assetId: value.assetId,
-        installed: value.installed === true,
-        name: value.name,
-        version: typeof value.version === "string" ? value.version : null,
-        description: typeof value.description === "string" ? value.description : null,
-        hasAgent: value.hasAgent === true,
-        server: value.server,
-        client: value.client
-    };
+    const parsed = parseProgramSnapshot(value);
+    if (parsed.installed === undefined)
+        throw new Error("The System returned a Program without installation state");
+    return { ...parsed, installed: parsed.installed };
 }
 function processState(value) {
     const identity = processIdentityState(value);
@@ -307,7 +297,7 @@ export function processIdentityState(value) {
     };
 }
 function windowState(value) {
-    if (!record(value) || typeof value.title !== "string" || typeof value.location !== "string" || typeof value.depth !== "number" || typeof value.minimized !== "boolean") {
+    if (!record(value) || typeof value.title !== "string" || typeof value.depth !== "number" || typeof value.minimized !== "boolean" || typeof value.maximized !== "boolean") {
         throw new Error("The System returned an invalid Window");
     }
     return {
@@ -316,8 +306,8 @@ function windowState(value) {
         size: value.size,
         depth: value.depth,
         minimized: value.minimized,
-        layer: value.layer,
-        location: value.location
+        maximized: value.maximized,
+        layer: value.layer
     };
 }
 function windowMessage(event, process) {
@@ -332,6 +322,8 @@ function windowMessage(event, process) {
         return window.title;
     if (event === "minimize")
         return window.minimized;
+    if (event === "maximize")
+        return window.maximized;
     return true;
 }
 function camel(value) { return value === "change-title" ? "changeTitle" : value; }

package/dist/system.d.ts

@@ -11,8 +11,7 @@ export declare class System implements CoreSystem {
     readonly program: SystemProgram;
     readonly process: SystemProcess;
     readonly uploads: SystemUploads;
-    fetch(input: RequestInfo | URL, init?: RequestInit): Promise<Response>;
-    websocket(url: string | URL, protocols?: string | string[]): Promise<WebSocket>;
+    readonly network: import("@phreshos/core").Network;
     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. */

package/dist/system.js

@@ -1,4 +1,4 @@
-import { ClientEndpoint as CoreClientEndpoint, ClientService as CoreClientService, Process as CoreProcess, Program as CoreProgram, ServerEndpoint as CoreServerEndpoint, ServerService as CoreServerService, isServiceKey, parseClientPermissions } from "@phreshos/core";
+import { ClientEndpoint as CoreClientEndpoint, ClientService as CoreClientService, Process as CoreProcess, Program as CoreProgram, ServerEndpoint as CoreServerEndpoint, ServerService as CoreServerService, isServiceKey, parseEndpointReference } from "@phreshos/core";
 import { homedir } from "node:os";
 import { gatewayAddress } from "./address.js";
 import Events from "./events.js";
@@ -11,13 +11,9 @@ import SystemRepresentation, { processIdentityState } from "./representation.js"
 import { GatewayConnection, openConnection } from "./transport.js";
 import Uploads from "./uploads.js";
 import shell from "./shell.js";
-import websocket from "./websocket.js";
+import network from "./network.js";
 const systems = new WeakMap();
 const processSnapshots = new WeakMap();
-const ProgramBase = CoreProgram;
-const ProcessBase = CoreProcess;
-const ServerEndpointBase = CoreServerEndpoint;
-const ClientEndpointBase = CoreClientEndpoint;
 /** One connected owner-local implementation of the shared System contract. */
 export class System {
     storage;
@@ -25,13 +21,7 @@ export class System {
     program;
     process;
     uploads;
-    async fetch(input, init) {
-        const request = new Request(input, init);
-        return await fetch(request, { signal: connectedSignal(this, request.signal) });
-    }
-    websocket(url, protocols) {
-        return websocket(url, protocols, connectedSignal(this));
-    }
+    network = network(() => connectedSignal(this));
     async *shell(command, options = {}) {
         yield* shell(command, { ...options, signal: connectedSignal(this, options.signal) });
     }
@@ -157,8 +147,11 @@ class ProgramRegistry extends Events {
         return event === "uninstall" ? { program, everything: values[1] === true } : program;
     }
 }
-class ProgramHandle extends ProgramBase {
+class ProgramHandle extends CoreProgram {
     system;
+    subscribe;
+    wait;
+    events;
     reference;
     identity;
     data;
@@ -177,11 +170,14 @@ class ProgramHandle extends ProgramBase {
         this.reference = snapshot.reference;
         this.identity = snapshot.identity;
         const address = this.address();
-        bindEvents(this, new Events(["forget", "uninstall"], (event, subscriber) => {
+        const events = new Events(["forget", "uninstall"], (event, subscriber) => {
             if (event === null)
                 throw new Error("Program events are named");
             return representation(system).on(`program:${this.reference}:${event}`, (...values) => subscriber(values[0]));
-        }));
+        });
+        this.subscribe = events.subscribe;
+        this.wait = events.wait;
+        this.events = events.events;
         representation(system).on(`program:${this.reference}:change`, value => this.update(value));
         const call = (event, ...values) => representation(system).call(event, ...values);
         this.data = filesystemStorage(() => programStoragePath(system, address, "data"), `Program "${this.identity}" data`, () => connectedSignal(system));
@@ -204,18 +200,7 @@ class ProgramHandle extends ProgramBase {
             service: this.snapshot.server.service
         }) : null;
     }
-    get client() {
-        return this.snapshot.client ? Object.freeze({
-            start: this.snapshot.client.start,
-            service: this.snapshot.client.service,
-            title: this.snapshot.client.title,
-            size: this.snapshot.client.size,
-            position: this.snapshot.client.position,
-            layer: this.snapshot.client.layer,
-            minimize: this.snapshot.client.minimize,
-            permissions: parseClientPermissions(this.snapshot.client.permissions)
-        }) : null;
-    }
+    get client() { return this.snapshot.client; }
     update(snapshot) {
         if (snapshot.reference !== this.reference)
             throw new Error("A Program handle cannot become another Program");
@@ -358,8 +343,11 @@ class ProcessRegistry extends Events {
         return process ? processHandle(this.system, process) : null;
     }
 }
-class ProcessHandle extends ProcessBase {
+class ProcessHandle extends CoreProcess {
     system;
+    subscribe;
+    wait;
+    events;
     identity;
     name;
     startedAt;
@@ -369,7 +357,10 @@ class ProcessHandle extends ProcessBase {
         super();
         this.system = system;
         processSnapshots.set(this, snapshot);
-        bindEvents(this, new Events(["exit"], (_event, subscriber) => (representation(system).on(`process:${snapshot.reference}:exit`, value => subscriber(value)))));
+        const events = new Events(["exit"], (_event, subscriber) => (representation(system).on(`process:${snapshot.reference}:exit`, value => subscriber(value))));
+        this.subscribe = events.subscribe;
+        this.wait = events.wait;
+        this.events = events.events;
         this.identity = snapshot.identity;
         this.name = snapshot.name;
         this.startedAt = new Date(snapshot.startedAt);
@@ -389,7 +380,10 @@ class ProcessHandle extends ProcessBase {
         });
         return value === null ? null : processHandle(this.system, processIdentityState(value));
     }
-    async option(name) { return processState(this.system, this).options[name]; }
+    async options(name) {
+        const options = processState(this.system, this).options;
+        return name === undefined ? Object.freeze({ ...options }) : options[name];
+    }
     async exit() {
         await representation(this.system).call("/process/exit", this.identity);
     }
@@ -432,9 +426,12 @@ class EndpointOperations extends Events {
         await representation(this.system).call(`/process/endpoint/${operation}`, this.owner.identity, this.endpoint, launch);
     }
 }
-class ServerEndpointHandle extends ServerEndpointBase {
+class ServerEndpointHandle extends CoreServerEndpoint {
     system;
     owner;
+    subscribe;
+    wait;
+    events;
     endpoint = "server";
     traffic;
     lifecycle;
@@ -446,7 +443,9 @@ class ServerEndpointHandle extends ServerEndpointBase {
         this.base = new EndpointOperations(system, owner, "server");
         this.traffic = new ServerTrafficHandle(representation(system), owner.identity, "server", value => endpointFromReference(system, value));
         this.lifecycle = this.base.lifecycle;
-        bindEvents(this, this.base);
+        this.subscribe = this.base.subscribe;
+        this.wait = this.base.wait;
+        this.events = this.base.events;
     }
     process() { return this.base.process(); }
     exists() { return this.base.exists(); }
@@ -454,7 +453,7 @@ class ServerEndpointHandle extends ServerEndpointBase {
     isService() { return this.base.isService(); }
     start(launch) { return this.base.start(launch); }
     stop() { return this.base.stop(); }
-    publish(event, payload) { return this.base.publish(event, payload); }
+    publish = (event, payload) => this.base.publish(event, payload);
     async ask(event, payload) {
         return await this.askWithin(event, payload, 10_000);
     }
@@ -465,7 +464,10 @@ class ServerEndpointHandle extends ServerEndpointBase {
         return representation(this.system).call("/process/endpoint/ask", this.owner.identity, event, payload, timeout);
     }
 }
-class ClientEndpointHandle extends ClientEndpointBase {
+class ClientEndpointHandle extends CoreClientEndpoint {
+    subscribe;
+    wait;
+    events;
     endpoint = "client";
     traffic;
     lifecycle;
@@ -476,7 +478,9 @@ class ClientEndpointHandle extends ClientEndpointBase {
         this.base = new EndpointOperations(system, owner, "client");
         this.traffic = new EndpointTrafficHandle(representation(system), owner.identity, "client", value => endpointFromReference(system, value));
         this.lifecycle = this.base.lifecycle;
-        bindEvents(this, this.base);
+        this.subscribe = this.base.subscribe;
+        this.wait = this.base.wait;
+        this.events = this.base.events;
         this.window = new SystemWindow(system, owner);
     }
     process() { return this.base.process(); }
@@ -485,13 +489,13 @@ class ClientEndpointHandle extends ClientEndpointBase {
     isService() { return this.base.isService(); }
     start(launch) { return this.base.start(launch); }
     stop() { return this.base.stop(); }
-    publish(event, payload) { return this.base.publish(event, payload); }
+    publish = (event, payload) => this.base.publish(event, payload);
 }
 class SystemWindow extends Events {
     system;
     process;
     constructor(system, process) {
-        super(["move", "resize", "geometry", "minimize", "changeTitle", "front"], (event, subscriber) => {
+        super(["move", "resize", "geometry", "minimize", "maximize", "changeTitle", "front"], (event, subscriber) => {
             if (event === null)
                 throw new Error("Window events are named");
             return representation(system).on(`window:${process.identity}:${event}`, subscriber);
@@ -503,13 +507,14 @@ class SystemWindow extends Events {
     async position() { return (await this.snapshot()).position; }
     async size() { return (await this.snapshot()).size; }
     async minimized() { return (await this.snapshot()).minimized; }
+    async maximized() { return (await this.snapshot()).maximized; }
     async front() { return frontWindow(this.system, this.process); }
     async layer() { return (await this.snapshot()).layer; }
-    async location() { return (await this.snapshot()).location; }
     async move(position) { await this.change("move", position); }
     async resize(size) { await this.change("resize", size); }
     async setGeometry(geometry) { await this.change("geometry", geometry); }
     async minimize(minimized = true) { await this.change("minimize", minimized); }
+    async maximize(maximized = true) { await this.change("maximize", maximized); }
     async changeTitle(title) { await this.change("change-title", title); }
     async raise() { await this.change("raise"); }
     snapshot() {
@@ -545,6 +550,9 @@ class ServerServiceHandle extends CoreServerService {
     system;
     key;
     lifecycle;
+    subscribe;
+    wait;
+    events;
     base;
     constructor(system, key) {
         super();
@@ -552,9 +560,12 @@ class ServerServiceHandle extends CoreServerService {
         this.key = key;
         this.base = new ServiceBase(system, key);
         this.lifecycle = this.base.lifecycle;
-        bindEvents(this, new Events([], (event, subscriber, impossible) => representation(system).follow({
+        const events = new Events([], (event, subscriber, impossible) => representation(system).follow({
             scope: "service", key, kind: "events", event
-        }, (_received, payload) => subscriber(payload), impossible)));
+        }, (_received, payload) => subscriber(payload), impossible));
+        this.subscribe = events.subscribe;
+        this.wait = events.wait;
+        this.events = events.events;
     }
     exists() { return this.base.exists(); }
     waitReady(timeout) { return this.base.waitReady(timeout); }
@@ -568,14 +579,20 @@ class ServerServiceHandle extends CoreServerService {
 }
 class ClientServiceHandle extends CoreClientService {
     lifecycle;
+    subscribe;
+    wait;
+    events;
     base;
     constructor(system, key) {
         super();
         this.base = new ServiceBase(system, key);
         this.lifecycle = this.base.lifecycle;
-        bindEvents(this, new Events([], (event, subscriber, impossible) => representation(system).follow({
+        const events = new Events([], (event, subscriber, impossible) => representation(system).follow({
             scope: "service", key, kind: "events", event
-        }, (_received, payload) => subscriber(payload), impossible)));
+        }, (_received, payload) => subscriber(payload), impossible));
+        this.subscribe = events.subscribe;
+        this.wait = events.wait;
+        this.events = events.events;
     }
     exists() { return this.base.exists(); }
     waitReady(timeout) { return this.base.waitReady(timeout); }
@@ -611,16 +628,6 @@ function programProcessEvent(system, event, values) {
     const process = processHandle(system, required(values[0]));
     return event === "exit" ? { process, ...values[1] } : process;
 }
-function bindEvents(target, events) {
-    Object.assign(target, eventsOf(events));
-}
-function eventsOf(events) {
-    return {
-        subscribe: events.subscribe,
-        waitFor: events.waitFor,
-        events: events.events
-    };
-}
 function chronological(left, right) { return left.startedAt.getTime() - right.startedAt.getTime(); }
 async function programStoragePath(system, handle, area) {
     const value = await representation(system).call("/program/area", handle, area, "path", []);
@@ -629,10 +636,9 @@ async function programStoragePath(system, handle, area) {
     return value;
 }
 function endpointFromReference(system, value) {
-    const reference = value;
-    if (!reference || (reference.kind !== "server" && reference.kind !== "client") || typeof reference.process?.identity !== "string") {
-        throw new Error("The System returned an invalid Endpoint reference");
-    }
+    if (value === null)
+        return null;
+    const reference = parseEndpointReference(value);
     const owner = processHandle(system, required(representation(system).processes.get(reference.process.identity), reference.process.identity));
     return reference.kind === "server" ? owner.server : owner.client;
 }

package/dist/traffic.d.ts

@@ -2,7 +2,7 @@ import type { AnswerSubscriber, AskSubscriber, Cleanup, Endpoint, EventOptions,
 import Events from "./events.js";
 import type SystemRepresentation from "./representation.js";
 type Kind = "publish" | "ask" | "answer";
-type ResolveEndpoint = (value: unknown) => Endpoint;
+type ResolveEndpoint = (value: unknown) => Endpoint | null;
 /** Directed traffic originating from one canonical Endpoint. */
 export declare class EndpointTrafficHandle<Definitions extends object = {}> extends Events<TrafficEvents<Definitions>, never> {
     private readonly representation;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@phreshos/node",
-  "version": "0.1.17",
+  "version": "0.1.19",
   "description": "Node.js access to PhreshOS and Program projects.",
   "type": "module",
   "main": "dist/main.js",
@@ -31,9 +31,8 @@
     "clean": "node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\"",
     "check": "tsc --noEmit && tsc -p tsconfig.test.json",
     "build": "node --run clean && tsc --noEmit false --outDir dist --rootDir source",
-    "test": "node --run build && node --test tests/*.test.mjs",
-    "verify:package": "node scripts/verify-package.mjs",
-    "verify": "node --run check && node --run test && node --run verify:package",
+    "test": "vitest run --project default",
+    "verify": "node --run check && node --run build && node --run test",
     "prepack": "node --run build"
   },
   "dependencies": {
@@ -43,12 +42,13 @@
     "jiti": "^2.7.0"
   },
   "peerDependencies": {
-    "@phreshos/core": "^0.1.42"
+    "@phreshos/core": "^0.1.44"
   },
   "devDependencies": {
-    "@phreshos/core": "^0.1.42",
+    "@phreshos/core": "^0.1.44",
     "@types/adm-zip": "^0.5.8",
     "@types/node": "^26.2.0",
-    "typescript": "^6.0.3"
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.10"
   }
 }