@phreshos/node 0.1.16 → 0.1.18

package/README.md

@@ -27,6 +27,9 @@ cross the connection boundary.
 | Bun | `bun add @phreshos/node` |
 | Yarn | `yarn add @phreshos/node` |
 
+`@phreshos/core` is a peer dependency and the single import path for shared
+System and runtime contracts.
+
 ```ts
 import { Project, System } from "@phreshos/node"
 
@@ -50,8 +53,14 @@ bun install --frozen-lockfile
 bun run verify
 ```
 
-`verify` checks the types, builds the package, and runs the connection and
-Project tests.
+`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
 

package/dist/content.d.ts

@@ -0,0 +1,8 @@
+import type { WritableContent } from "@phreshos/core";
+/** Encodes one writable value without assigning it to Storage or Uploads. */
+export declare function content(value: WritableContent): EncodedContent;
+export interface EncodedContent {
+    stream: ReadableStream<Uint8Array>;
+    extension: string;
+    type: string;
+}

package/dist/content.js

@@ -0,0 +1,36 @@
+/** Encodes one writable value without assigning it to Storage or Uploads. */
+export function content(value) {
+    const binary = "application/octet-stream";
+    if (typeof File !== "undefined" && value instanceof File) {
+        const type = value.type || binary;
+        return { stream: value.stream(), extension: extension(value.name, type), type };
+    }
+    if (typeof Blob !== "undefined" && value instanceof Blob) {
+        const type = value.type || binary;
+        return { stream: value.stream(), extension: extension("", type), type };
+    }
+    if (value instanceof ReadableStream)
+        return { stream: value, extension: "bin", type: binary };
+    if (typeof value === "string")
+        return { stream: new Blob([value]).stream(), extension: "txt", type: "text/plain" };
+    if (value instanceof ArrayBuffer)
+        return { stream: new Blob([value]).stream(), extension: "bin", type: binary };
+    if (ArrayBuffer.isView(value)) {
+        const bytes = new Uint8Array(value.byteLength);
+        bytes.set(new Uint8Array(value.buffer, value.byteOffset, value.byteLength));
+        return { stream: new Blob([bytes]).stream(), extension: "bin", type: binary };
+    }
+    const json = JSON.stringify(value);
+    if (json === undefined)
+        throw new Error("Writable content must have a JSON representation");
+    return { stream: new Blob([json]).stream(), extension: "json", type: "application/json" };
+}
+const extensions = {
+    "application/gzip": "gz", "application/javascript": "js", "application/json": "json", "application/pdf": "pdf",
+    "application/wasm": "wasm", "application/zip": "zip", "audio/mpeg": "mp3", "image/gif": "gif", "image/jpeg": "jpg",
+    "image/png": "png", "image/svg+xml": "svg", "image/webp": "webp", "text/css": "css", "text/csv": "csv",
+    "text/html": "html", "text/javascript": "js", "text/plain": "txt", "video/mp4": "mp4"
+};
+function extension(name, type) {
+    return name.match(/\.([A-Za-z0-9]+)$/)?.[1]?.toLowerCase() ?? extensions[type.split(";", 1)[0].toLowerCase()] ?? "bin";
+}

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/main.d.ts

@@ -1,5 +1,4 @@
 export { gatewayAddress } from "./address.js";
-export { ClientEndpoint, ClientService, Endpoint, Process, Program, ServerEndpoint, ServerService, System, type ProgramProcessRunEvent, type ProgramProcessRunOptions } from "./system.js";
-export { Service, clientPermissionCatalog, isPermissionName, type ClientLaunch, type Launch, type Permission, type PermissionDefinition, type PermissionDefinitions, type PermissionInput, type PermissionName, type PermissionRequest, type PermissionValue, type PermissionValueDomain, type Permissions, type ProgramPermissions, type ProgramDefinition, type ServerLaunch, type ServiceKey, type ShellEvent, type ShellOptions, type ProgramStartup, type Storage, } from "@phreshos/core";
+export { System } from "./system.js";
 export { resolveHome } from "./home.js";
 export { Project, type Manifest, type PackedProject, type ProjectMode, type ProjectOptions, type ProjectRunOptions } from "./project.js";

package/dist/main.js

@@ -1,5 +1,4 @@
 export { gatewayAddress } from "./address.js";
-export { ClientEndpoint, ClientService, Endpoint, Process, Program, ServerEndpoint, ServerService, System } from "./system.js";
-export { Service, clientPermissionCatalog, isPermissionName, } from "@phreshos/core";
+export { System } from "./system.js";
 export { resolveHome } from "./home.js";
 export { Project } from "./project.js";

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

@@ -61,34 +61,45 @@ 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,
+            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() {
@@ -135,7 +146,7 @@ export class Project {
     }
     async prepareDevelopment(system, development, options) {
         const client = await DevelopmentClient.prepare(development, this.directory);
-        const program = await system.forceCreateProgram(this.definition("development", client.url));
+        const program = await system.program.forceCreate(this.definition("development", client.url));
         try {
             await client.start(program.assetId, options.signal);
             const lifecycle = program.process.run({ options: options.options ?? {} }, { signal: client.processSignal(options.signal) });
@@ -150,7 +161,7 @@ export class Project {
     /** Build this Project and return its Program installation generator. */
     async install(system) {
         await this.build();
-        const program = await system.forceCreateProgram(this.productionDefinition());
+        const program = await system.program.forceCreate(this.productionDefinition());
         return program.install();
     }
     /** Build and package this Program into its canonical release shape. */
@@ -184,7 +195,7 @@ export class Project {
         return Object.freeze({ archive, archivePath, checksumPath, declarationPath, digest });
     }
     async run(system, definition, options) {
-        const program = await system.forceCreateProgram(definition);
+        const program = await system.program.forceCreate(definition);
         return program.process.run({ options: options.options ?? {} }, { signal: options.signal });
     }
 }
@@ -326,6 +337,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/storage.d.ts

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

package/dist/storage.js

@@ -1,111 +1,244 @@
+import { Storage, StorageFile } from "@phreshos/core";
 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, resolve as resolvePath, sep } from "node:path";
+import { createReadStream, createWriteStream, linkSync, lstatSync, mkdirSync, readdirSync, renameSync, rmSync, statfsSync, statSync } from "node:fs";
+import { rm, watch as watchPath } from "node:fs/promises";
+import { basename, dirname, isAbsolute, join, relative, resolve as resolvePath, sep } from "node:path";
 import { Readable } from "node:stream";
 import { pipeline } from "node:stream/promises";
+import { content } from "./content.js";
 /** Create one filesystem implementation bounded beneath a resolved absolute root. */
 export function filesystemStorage(source, label, lifetime) {
-    return createStorage(source, label, contained, lifetime);
+    return new NodeStorage(new StorageBoundary(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);
+    return new NodeStorage(new StorageBoundary(source, label, native, 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);
+class StorageBoundary {
+    source;
+    label;
+    locate;
+    lifetime;
+    root = null;
+    constructor(source, label, locate, lifetime) {
+        this.source = source;
+        this.label = label;
+        this.locate = locate;
+        this.lifetime = lifetime;
+    }
+    active() {
+        const signal = this.lifetime?.();
+        signal?.throwIfAborted();
+        return signal;
+    }
+    async path(parts) {
+        return this.locate(await this.rootPath(), parts);
+    }
+    rootPath() {
+        this.active();
+        if (!this.root) {
+            const resolving = Promise.resolve(typeof this.source === "string" ? this.source : this.source()).then(value => {
+                this.active();
                 if (!isAbsolute(value))
                     throw new Error("A Storage root must be absolute");
                 return value;
             });
-        return root;
-    };
-    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 retained = resolving.catch(error => {
+                if (this.root === retained)
+                    this.root = null;
+                throw error;
+            });
+            this.root = retained;
+        }
+        return this.root;
+    }
+}
+class NodeStorage extends Storage {
+    boundary;
+    parts;
+    constructor(boundary, parts) {
+        super();
+        this.boundary = boundary;
+        this.parts = parts;
+    }
+    async name() { const path = await this.path(); return basename(path) || path; }
+    path() { return this.boundary.path(this.parts); }
+    navigate(...parts) {
+        return new NodeStorage(this.boundary, [...this.parts, ...parts]);
+    }
+    file(...parts) {
+        return new NodeStorageFile(this.boundary, [...this.parts, ...parts]);
+    }
+    async create() {
+        this.boundary.active();
+        mkdirSync(await this.path(), { recursive: true });
+    }
+    async stat() {
+        this.boundary.active();
+        const value = describe(await this.path());
+        if (!value)
+            return null;
+        if (value.kind !== "storage")
+            throw new Error(`${await this.path()} is not a Storage directory`);
+        return value.stat;
+    }
+    async list(options = {}) {
+        this.boundary.active();
+        const depth = listDepth(options);
+        const entries = [];
+        await this.collect(entries, [], depth);
+        return entries;
+    }
+    async collect(entries, relativeParts, depth) {
+        if (depth === 0)
+            return;
+        const location = this.navigate(...relativeParts);
+        const found = await location.stat();
+        if (!found)
+            throw new Error(`There is no ${await location.path()} in ${this.boundary.label}`);
+        for (const name of readdirSync(await location.path()).sort()) {
+            const childParts = [...relativeParts, name];
+            const child = describe(await this.boundary.path([...this.parts, ...childParts]));
+            if (!child)
+                continue;
+            if (child.kind === "file")
+                entries.push(this.file(...childParts));
+            else {
+                entries.push(this.navigate(...childParts));
+                if (depth > 1)
+                    await this.collect(entries, childParts, depth - 1);
+            }
+        }
+    }
+    async copy(destination, options = {}) {
+        await copyStorage(this, destination, options);
+    }
+    async move(destination, options = {}) {
+        const [sourcePath, destinationPath] = await Promise.all([this.path(), destination.path()]);
+        if (samePath(sourcePath, destinationPath))
+            return;
+        await copyStorage(this, destination, options);
+        await this.delete();
+    }
+    async delete() {
+        this.boundary.active();
+        rmSync(await this.path(), { recursive: true, force: true });
+    }
+    async clear() {
+        this.boundary.active();
+        const destination = await this.path();
         const found = describe(destination);
+        if (found?.kind === "file")
+            throw new Error("Only a Storage directory can be cleared");
+        rmSync(destination, { recursive: true, force: true });
+        mkdirSync(destination, { recursive: true });
+    }
+    async space() {
+        this.boundary.active();
+        const value = statfsSync(await this.path());
+        const capacity = value.blocks * value.bsize;
+        const available = value.bavail * value.bsize;
+        return { capacity, available, used: capacity - value.bfree * value.bsize };
+    }
+    async *watch(options = {}) {
+        const lifetime = this.boundary.active();
+        const signal = combinedSignal(lifetime, options.signal);
+        for await (const change of watchPath(await this.path(), { recursive: options.recursive, signal })) {
+            yield { event: change.eventType, path: change.filename === null ? null : String(change.filename) };
+        }
+    }
+}
+class NodeStorageFile extends StorageFile {
+    boundary;
+    parts;
+    constructor(boundary, parts) {
+        super();
+        this.boundary = boundary;
+        this.parts = parts;
+    }
+    async name() { const path = await this.path(); return basename(path) || path; }
+    path() { return this.boundary.path(this.parts); }
+    async stat() {
+        this.boundary.active();
+        const value = describe(await this.path());
+        if (!value)
+            return null;
+        if (value.kind !== "file")
+            throw new Error(`${await this.path()} is not a file`);
+        return value.stat;
+    }
+    async stream(options = {}) {
+        const signal = this.boundary.active();
+        const destination = await this.path();
+        const found = await this.stat();
         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, { signal }));
-    }
-    async function write(...args) {
-        const signal = active(lifetime);
-        const parts = args.slice(0, -1);
-        const destination = await resolve(...parts);
+            throw new Error(`There is no ${this.parts.join("/")} in ${this.boundary.label}`);
+        if (options.length === 0)
+            return new ReadableStream({ start(controller) { controller.close(); } });
+        const range = readRange(options);
+        return Readable.toWeb(createReadStream(destination, { ...range, signal }));
+    }
+    async bytes(options) {
+        return new Uint8Array(await new Response(await this.stream(options)).arrayBuffer());
+    }
+    async text(options) {
+        return new Response(await this.stream(options)).text();
+    }
+    async json() {
+        return JSON.parse(await this.text());
+    }
+    async write(value, options = {}) {
+        const signal = this.boundary.active();
+        const destination = await this.path();
         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" }), { signal });
+            await pipeline(Readable.fromWeb(content(value).stream), createWriteStream(temporary, { flags: "wx" }), { signal });
             signal?.throwIfAborted();
-            renameSync(temporary, destination);
+            if (options.overwrite === false) {
+                linkSync(temporary, destination);
+                rmSync(temporary, { force: true });
+            }
+            else
+                renameSync(temporary, destination);
         }
         catch (error) {
             await rm(temporary, { force: true }).catch(() => undefined);
             throw error;
         }
     }
-    return {
-        path,
-        resolve,
-        stream,
-        async bytes(...parts) { return new Uint8Array(await new Response(await stream(...parts)).arrayBuffer()); },
-        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) { 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")
-                throw new Error("Only a Storage directory can be cleared");
-            rmSync(destination, { recursive: true, force: true });
-            mkdirSync(destination, { recursive: true });
-        }
-    };
-}
-function active(lifetime) {
-    const signal = lifetime?.();
-    signal?.throwIfAborted();
-    return signal;
-}
-function content(value) {
-    if (value instanceof ReadableStream)
-        return value;
-    if (value instanceof Uint8Array)
-        return new Blob([bytes(value)]).stream();
-    if (value instanceof ArrayBuffer)
-        return new Blob([value]).stream();
-    if (typeof Blob !== "undefined" && value instanceof Blob)
-        return value.stream();
-    if (typeof value === "string")
-        return new Blob([value]).stream();
-    return new Blob([JSON.stringify(value)]).stream();
+    async append(value) {
+        const signal = this.boundary.active();
+        const destination = await this.path();
+        mkdirSync(dirname(destination), { recursive: true });
+        await pipeline(Readable.fromWeb(content(value).stream), createWriteStream(destination, { flags: "a" }), { signal });
+    }
+    async copy(destination, options = {}) {
+        const [sourcePath, destinationPath] = await Promise.all([this.path(), destination.path()]);
+        if (samePath(sourcePath, destinationPath))
+            return;
+        await destination.write(await this.stream(), { overwrite: options.overwrite ?? false });
+    }
+    async move(destination, options = {}) {
+        const [sourcePath, destinationPath] = await Promise.all([this.path(), destination.path()]);
+        if (samePath(sourcePath, destinationPath))
+            return;
+        await this.copy(destination, options);
+        await this.delete();
+    }
+    async delete() {
+        this.boundary.active();
+        rmSync(await this.path(), { force: true });
+    }
 }
-function bytes(value) {
-    return value.buffer.slice(value.byteOffset, value.byteOffset + value.byteLength);
+function native(root, parts) {
+    return resolvePath(root, ...parts);
 }
 function contained(root, parts) {
     const destination = join(root, ...parts);
     const step = relative(root, destination);
     if (step === ".." || step.startsWith(`..${sep}`) || isAbsolute(step))
-        throw new Error("A Storage path may not leave its configured directory");
+        throw new Error("A Storage path may not leave its configured boundary");
     let current = root;
     for (const part of step.split(sep).filter(Boolean)) {
         current = join(current, part);
@@ -131,9 +264,66 @@ function describe(path) {
             return null;
         throw error;
     }
+    const modifiedAt = Math.round(value.mtimeMs);
     if (value.isFile())
-        return { kind: "file", size: value.size, modifiedAt: value.mtimeMs };
+        return { kind: "file", stat: { size: value.size, modifiedAt } };
     if (value.isDirectory())
-        return { kind: "directory", modifiedAt: value.mtimeMs };
-    return { kind: "other", modifiedAt: value.mtimeMs };
+        return { kind: "storage", stat: { modifiedAt } };
+    throw new Error(`${path} is neither a file nor a Storage directory`);
+}
+function readRange(options) {
+    const offset = options.offset ?? 0;
+    if (!Number.isSafeInteger(offset) || offset < 0)
+        throw new Error("A Storage read offset must be a non-negative safe integer");
+    if (options.length === undefined)
+        return { start: offset };
+    if (!Number.isSafeInteger(options.length) || options.length < 0)
+        throw new Error("A Storage read length must be a non-negative safe integer");
+    if (!Number.isSafeInteger(offset + options.length))
+        throw new Error("A Storage byte range must use safe integers");
+    return { start: offset, end: offset + options.length - 1 };
+}
+function listDepth(options) {
+    if (options.depth !== undefined && (!Number.isSafeInteger(options.depth) || options.depth < 0)) {
+        throw new Error("A Storage list depth must be a non-negative safe integer");
+    }
+    if (options.depth !== undefined && !options.recursive)
+        throw new Error("A Storage list depth requires recursive listing");
+    if (!options.recursive)
+        return 1;
+    return options.depth ?? Number.POSITIVE_INFINITY;
+}
+async function copyStorage(source, destination, options) {
+    const [sourcePath, destinationPath] = await Promise.all([source.path(), destination.path()]);
+    if (samePath(sourcePath, destinationPath))
+        return;
+    if (descendsFrom(destinationPath, sourcePath))
+        throw new Error("A Storage directory cannot be copied inside itself");
+    if (!await source.stat())
+        throw new Error(`There is no Storage directory at ${sourcePath}`);
+    if (await destination.stat()) {
+        if (!options.overwrite)
+            throw new Error(`A Storage directory already exists at ${destinationPath}`);
+        await destination.delete();
+    }
+    await destination.create();
+    for (const entry of await source.list()) {
+        const name = await entry.name();
+        if (entry instanceof StorageFile)
+            await entry.copy(destination.file(name), options);
+        else
+            await entry.copy(destination.navigate(name), options);
+    }
+}
+function samePath(left, right) {
+    return resolvePath(left) === resolvePath(right);
+}
+function descendsFrom(path, parent) {
+    const step = relative(parent, path);
+    return step !== "" && step !== ".." && !step.startsWith(`..${sep}`) && !isAbsolute(step);
+}
+function combinedSignal(left, right) {
+    if (left && right)
+        return AbortSignal.any([left, right]);
+    return left ?? right;
 }

package/dist/system.d.ts

@@ -1,11 +1,9 @@
-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;
+import { ClientService as CoreClientService, ServerService as CoreServerService, type ServiceKey, type ShellOptions, type System as CoreSystem, type SystemProcess, type SystemProgram, type SystemUploads, type Storage, type WritableAppearance } from "@phreshos/core";
 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>;
+type ServiceHandle<Endpoint extends ServiceEndpoint, EventsMap extends object, Fallback = unknown> = Endpoint extends "server" ? CoreServerService<EventsMap, Fallback> : CoreClientService<EventsMap, Fallback>;
 /** One connected owner-local implementation of the shared System contract. */
 export declare class System implements CoreSystem {
     readonly storage: Storage;
@@ -13,36 +11,15 @@ 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. */
     static connect(home?: string): Promise<System>;
-    /** Atomically replace one runtime Program without touching its installed form. */
-    forceCreateProgram(source: ProgramDefinition | string): Promise<Program>;
     /** Close this owner connection and abort every attached operation it owns. */
     disconnect(): Promise<void>;
     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>;
+    service<EventsMap extends object = {}, Fallback = unknown>(key: ServiceAddress<"server">): CoreServerService<EventsMap, Fallback>;
+    service<EventsMap extends object = {}, Fallback = unknown>(key: ServiceAddress<"client">): CoreClientService<EventsMap, Fallback>;
 }
-/** 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. */
-export declare class ClientService<EventsMap extends object = {}, Fallback = unknown> extends CoreClientService<EventsMap, Fallback> {
-    protected constructor();
-}
-export type Program = CoreProgram;
-export declare const Program: typeof CoreProgram;
-export type Process = CoreProcess;
-export declare const Process: typeof CoreProcess;
-export type Endpoint<EventsMap extends object = {}, Fallback = unknown> = CoreEndpoint<EventsMap, Fallback>;
-export declare const Endpoint: typeof CoreEndpoint;
-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,4 +1,4 @@
-import { ClientEndpoint as CoreClientEndpoint, ClientService as CoreClientService, Endpoint as CoreEndpoint, 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) });
     }
@@ -54,12 +44,6 @@ export class System {
         const address = gatewayAddress(resolved);
         return new System(await openConnection(address));
     }
-    /** Atomically replace one runtime Program without touching its installed form. */
-    async forceCreateProgram(source) {
-        requireConnected(this);
-        const identity = await representation(this).call("/program/force-create-program", source, "");
-        return programHandle(this, required(representation(this).programs.get(identity), identity));
-    }
     /** Close this owner connection and abort every attached operation it owns. */
     async disconnect() {
         await closeSystem(this, new Error("This System connection is closed"));
@@ -153,13 +137,21 @@ class ProgramRegistry extends Events {
         const identity = await representation(this.system).call("/program/create-program", source);
         return programHandle(this.system, required(representation(this.system).programs.get(identity), identity));
     }
+    async forceCreate(source) {
+        requireConnected(this.system);
+        const identity = await representation(this.system).call("/program/force-create-program", source, "");
+        return programHandle(this.system, required(representation(this.system).programs.get(identity), identity));
+    }
     event(event, values) {
         const program = programHandle(this.system, required(values[0]));
         return event === "uninstall" ? { program, everything: values[1] === true } : program;
     }
 }
-class ProgramHandle extends ProgramBase {
+class ProgramHandle extends CoreProgram {
     system;
+    subscribe;
+    wait;
+    events;
     reference;
     identity;
     data;
@@ -178,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));
@@ -205,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");
@@ -359,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;
@@ -370,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);
@@ -390,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);
     }
@@ -433,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;
@@ -447,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(); }
@@ -455,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);
     }
@@ -466,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;
@@ -477,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(); }
@@ -486,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);
@@ -504,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() {
@@ -542,14 +546,13 @@ class ServiceBase {
         void representation(this.system).call("/process/service/publish", this.key, event, payload);
     }
 }
-/** Node SDK handle for a Service provided by a Server Endpoint. */
-export class ServerService extends CoreServerService {
-    constructor() { super(); }
-}
-class ServerServiceHandle extends ServerService {
+class ServerServiceHandle extends CoreServerService {
     system;
     key;
     lifecycle;
+    subscribe;
+    wait;
+    events;
     base;
     constructor(system, key) {
         super();
@@ -557,9 +560,12 @@ class ServerServiceHandle extends ServerService {
         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); }
@@ -571,20 +577,22 @@ class ServerServiceHandle extends ServerService {
         return { ask: (event, payload) => representation(this.system).call("/process/service/ask", this.key, event, payload, milliseconds) };
     }
 }
-/** Node SDK handle for a Service provided by a Client Endpoint. */
-export class ClientService extends CoreClientService {
-    constructor() { super(); }
-}
-class ClientServiceHandle extends ClientService {
+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); }
@@ -620,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", []);
@@ -638,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;
 }
@@ -715,8 +712,3 @@ function required(value, identity = "") {
         return value;
     throw new Error(`The System returned no ${identity ? `${identity} ` : ""}snapshot`);
 }
-export const Program = CoreProgram;
-export const Process = CoreProcess;
-export const Endpoint = CoreEndpoint;
-export const ServerEndpoint = CoreServerEndpoint;
-export const ClientEndpoint = CoreClientEndpoint;

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/dist/uploads.d.ts

@@ -1,4 +1,4 @@
-import { type SystemUploads, type Upload } from "@phreshos/core";
+import { type SystemUploads, type Upload, type WritableContent } from "@phreshos/core";
 type Ask = (request: object) => Promise<unknown>;
 /** Owner-local implementation of the System's opaque upload collection. */
 export default class Uploads implements SystemUploads {
@@ -7,16 +7,14 @@ export default class Uploads implements SystemUploads {
     private accessPromise;
     constructor(ask: Ask, lifetime: () => AbortSignal);
     path(): Promise<string>;
-    write(value: unknown): Promise<Upload>;
+    write(value: WritableContent): Promise<Upload>;
     stream(file: string): Promise<ReadableStream<Uint8Array<ArrayBufferLike>>>;
     bytes(file: string): Promise<Uint8Array<ArrayBuffer>>;
     text(file: string): Promise<string>;
     json<Value>(file: string): Promise<Value>;
     stat(file: string): Promise<Readonly<{
-        file: string;
-        type: string | null;
         size: number;
-        time: number;
+        modifiedAt: number;
     }> | null>;
     private access;
     private active;

package/dist/uploads.js

@@ -5,6 +5,7 @@ import { rename, rm } from "node:fs/promises";
 import { isAbsolute, join } from "node:path";
 import { Readable } from "node:stream";
 import { pipeline } from "node:stream/promises";
+import { content } from "./content.js";
 /** Owner-local implementation of the System's opaque upload collection. */
 export default class Uploads {
     ask;
@@ -46,7 +47,7 @@ export default class Uploads {
         const upload = await this.stat(file);
         if (!upload)
             throw new Error("The completed upload could not be described");
-        return upload;
+        return { file, ...upload };
     }
     async stream(file) {
         const signal = this.active();
@@ -90,36 +91,3 @@ function requireFile(file) {
     if (!isUploadFile(file))
         throw new Error("That is not an upload file");
 }
-function content(value) {
-    if (typeof File !== "undefined" && value instanceof File) {
-        const type = value.type || "application/octet-stream";
-        return { stream: value.stream(), extension: extension(value.name, type) };
-    }
-    if (typeof Blob !== "undefined" && value instanceof Blob)
-        return { stream: value.stream(), extension: extension("", value.type) };
-    if (value instanceof ReadableStream)
-        return { stream: value, extension: "bin" };
-    if (value instanceof Uint8Array)
-        return { stream: new Blob([bytes(value)]).stream(), extension: "bin" };
-    if (value instanceof ArrayBuffer)
-        return { stream: new Blob([value]).stream(), extension: "bin" };
-    if (typeof value === "string")
-        return { stream: new Blob([value]).stream(), extension: "txt" };
-    return { stream: new Blob([JSON.stringify(value)]).stream(), extension: "json" };
-}
-function bytes(value) {
-    return value.buffer.slice(value.byteOffset, value.byteOffset + value.byteLength);
-}
-function extension(name, type) {
-    const named = /\.([a-z0-9]+)$/i.exec(name)?.[1]?.toLowerCase();
-    if (named && /^[a-z0-9]+$/.test(named))
-        return named;
-    return extensions[type] ?? "bin";
-}
-const extensions = {
-    "application/json": "json",
-    "image/jpeg": "jpg",
-    "image/png": "png",
-    "image/svg+xml": "svg",
-    "text/plain": "txt"
-};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@phreshos/node",
-  "version": "0.1.16",
+  "version": "0.1.18",
   "description": "Node.js access to PhreshOS and Program projects.",
   "type": "module",
   "main": "dist/main.js",
@@ -31,20 +31,24 @@
     "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": "node --run check && node --run test",
+    "test": "vitest run --project default",
+    "verify": "node --run check && node --run build && node --run test",
     "prepack": "node --run build"
   },
   "dependencies": {
-    "@phreshos/core": "^0.1.41",
     "@the-link/ipc": "^0.2.1",
     "@the-link/messagepack": "^0.1.0",
     "adm-zip": "^0.6.0",
     "jiti": "^2.7.0"
   },
+  "peerDependencies": {
+    "@phreshos/core": "^0.1.43"
+  },
   "devDependencies": {
+    "@phreshos/core": "^0.1.43",
     "@types/adm-zip": "^0.5.8",
     "@types/node": "^26.2.0",
-    "typescript": "^6.0.3"
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.10"
   }
 }