@phreshos/server 0.1.17 → 0.1.19

package/README.md

@@ -10,47 +10,38 @@ active testing. The architecture's components will be released in stages as
 their contracts and integrations are verified.
 
 `@phreshos/server` is not intended to be used on its own. It requires the
-shared contracts from `@phreshos/core` and a compatible system host to provide
+shared contracts from `@phreshos/core` and a compatible System runtime to provide
 its runtime boundary.
 
 It uses the domain objects and shared contracts from `@phreshos/core` through
 a peer dependency. It does not redefine those objects, own client-side
-capabilities, or contain host and transport implementations.
-
-Its `Host` contract exposes the observable system Theme with replacement
-authority, authoritative Program and Process discovery, runtime Program
-creation, lifecycle events, and publicly served values. `host.theme.snapshot()`
-explicitly and asynchronously reads the current value,
-`subscribe("change", listener)` receives only complete replacements published
-after registration, and `update()` asynchronously validates and replaces the
-Theme through the system authority. A subscription has no initial delivery or
-replay.
-
-`host.signInWallpaper` and `host.desktopWallpaper` are independent direct Host
-capabilities. A served image or HTML file is selected by its generated
-filename, while the desktop may instead select a Program that declares a
-Client:
+capabilities, or contain System and transport implementations.
+
+Its `System` contract exposes the complete unresolved Appearance with
+replacement authority, authoritative Program and Process discovery, runtime
+Program creation, lifecycle events, and flat public uploads.
+`system.appearance.snapshot()` explicitly reads current authoritative state;
+`subscribe("change", listener)` receives only replacements published after
+registration, and `update()` validates and persists a complete replacement.
+Wallpaper filenames are ordinary Appearance values rather than separate SDK
+capabilities:
 
 ```ts
-const served = await host.serve(file)
-
-await host.signInWallpaper.set(served.file)
-await host.desktopWallpaper.set(served.file)
-await host.desktopWallpaper.setProgram(program, {
-  name: "wallpaper",
-  server: false,
-  client: { location: "/ambient" },
-  options: { mode: "calm" }
+const upload = await system.uploads.write(file)
+const bytes = await system.uploads.bytes(upload.file)
+const appearance = await system.appearance.snapshot()
+
+await system.appearance.update({
+  ...appearance,
+  desktopWallpaper: {
+    ...appearance.desktopWallpaper,
+    light: upload.file
+  }
 })
 
-await host.signInWallpaper.remove()
-await host.desktopWallpaper.remove()
+void bytes
 ```
 
-Selecting or removing a desktop choice exits the previous wallpaper Process.
-Its Client and visual state are system-managed; complete Process exit remains
-available and reveals the bundled desktop fallback.
-
 Its JavaScript entry point adapts the Process IPC boundary to these contracts.
 The SDK owns callbacks, waits, queues, and their cleanup; the boundary owns
 only the forwarding registrations requested by the SDK.
@@ -84,7 +75,7 @@ resulting desktop material.
 The package provides two contextual runtime entry points:
 
 ```ts
-import { host, current } from "@phreshos/server"
+import { system, current } from "@phreshos/server"
 ```
 
 It also re-exports the shared Core runtime classes—`Program`, `Process`,
@@ -115,26 +106,26 @@ generator that opens immediately, yields ordered `stdout` and `stderr` command
 chunks, completes only after installation succeeds, and throws the owning
 System error when installation fails. Their `Storage` values also expose
 `path()` and traversal-safe `resolve()`, because filesystem work is performed
-locally in the Server SDK after the Host supplies only the area root.
-Object descriptions passed to `host.program.create()` therefore require an
+locally in the Server SDK after the System supplies only the area root.
+Object descriptions passed to `system.program.create()` therefore require an
 explicit absolute storage root as well as at least one declared Endpoint.
 
-`host.storage` implements that same refined `Storage` contract against the
+`system.storage` implements that same refined `Storage` contract against the
 native operating-system home directory. The System supplies the authoritative
 root; traversal and symbolic-link escape remain rejected by the SDK before any
 filesystem operation.
 
-Host registries are separated by owner. Reads, commands, and the complete
+System registries are separated by owner. Reads, commands, and the complete
 subscription contract live on their relevant capability rather than directly
-on `host`:
+on `system`:
 
 ```ts
-const programs = await host.program.list()
-const program = await host.program.find("counter")
-const processes = await host.process.list()
+const programs = await system.program.list()
+const program = await system.program.find("counter")
+const processes = await system.process.list()
 
-const stopPrograms = host.program.subscribe("create", value => undefined)
-const stopProcesses = host.process.subscribe("exit", value => undefined)
+const stopPrograms = system.program.subscribe("create", value => undefined)
+const stopProcesses = system.process.subscribe("exit", value => undefined)
 ```
 
 A Program owns its scoped Process capability:
@@ -154,7 +145,7 @@ const shared = await program.process.findOrCreate({
 launches converge on one named Process; a different launch for that name
 rejects instead of reconfiguring the existing Process.
 
-`host.service(key)` creates the exact opaque service handle. The
+`system.service(key)` creates the exact opaque service handle. The
 handler exposes its authored `name`, `enabled()`, `waitReady()`, lifecycle
 subscriptions, and channel; it does not expose its Program or Endpoint as
 separate fields. Services are runtime bindings explicitly enabled by their

package/dist/appearance.d.ts

@@ -0,0 +1,17 @@
+import { type Appearance } from "@phreshos/core";
+import Events from "./events.js";
+/** System Appearance authority reached explicitly through the Server boundary. */
+export default class ServerAppearance extends Events {
+    constructor();
+    snapshot(): Promise<Readonly<{
+        background: import("@phreshos/core").ThemedValue<string, string>;
+        foreground: import("@phreshos/core").ThemedValue<string, string>;
+        accent: import("@phreshos/core").ThemedValue<string, string>;
+        spacing: import("@phreshos/core").ThemedValue<number>;
+        radius: import("@phreshos/core").ThemedValue<number>;
+        surface: import("@phreshos/core").ThemedValue<import("@phreshos/core").AppearanceSurface, import("@phreshos/core").AppearanceSurface>;
+        signInWallpaper: import("@phreshos/core").ThemedValue<string | null, string | null>;
+        desktopWallpaper: import("@phreshos/core").ThemedValue<string | null, string | null>;
+    }>>;
+    readonly update: (appearance: Appearance) => Promise<void>;
+}

package/dist/appearance.js

@@ -0,0 +1,21 @@
+import { createAppearanceSnapshot } from "@phreshos/core";
+import Events from "./events.js";
+import wire from "./wire.js";
+/** System Appearance authority reached explicitly through the Server boundary. */
+export default class ServerAppearance extends Events {
+    constructor() {
+        super((event, listener, impossible) => wire.on("host-appearance", event, value => {
+            listener(createAppearanceSnapshot(value));
+        }, null, impossible), observer => wire.onAll("host-appearance", (event, value) => {
+            if (typeof event === "string")
+                observer(event, createAppearanceSnapshot(value));
+        }));
+    }
+    async snapshot() {
+        const [appearance] = await wire.request(["appearance"]);
+        return createAppearanceSnapshot(appearance);
+    }
+    update = async (appearance) => {
+        await wire.request(["update-appearance", appearance]);
+    };
+}

package/dist/channel.d.ts

@@ -1,9 +1,15 @@
-import type { Channel as CoreChannel, ChannelMessage, Cleanup } from "@phreshos/core";
+import type { Channel as CoreChannel, ChannelCapture as CoreChannelCapture, ChannelEvents as CoreChannelEvents, ChannelMessage as CoreChannelMessage, Cleanup } from "@phreshos/core";
 import { type Endpoint } from "./domain.js";
+/** One value addressed to the current Server, with a server-visible sender. */
+export type ChannelMessage<Payload = unknown> = CoreChannelMessage<Payload, Endpoint | null>;
 /** Handles one question addressed to the current Server. */
 export type Answerer<Payload = unknown, Result = undefined> = (message: ChannelMessage<Payload>) => Result | Promise<Result>;
+/** Applies the server-visible sender envelope to known Channel events. */
+export type ChannelEvents<Events extends object> = CoreChannelEvents<Events, Endpoint | null>;
+/** Every event observable through the current Server's Channel. */
+export type ChannelCapture<Events extends object = {}> = CoreChannelCapture<Events, Endpoint | null>;
 /** Events and questions explicitly accepted by the current Server. */
-export interface Channel<Events extends object = {}> extends CoreChannel<Events, Endpoint> {
+export interface Channel<Events extends object = {}> extends CoreChannel<Events, Endpoint | null> {
     /** Registers one answerer; omitting its return produces `undefined`. */
     answer<Payload = unknown, Result = undefined>(event: string, answerer: Answerer<Payload, Result>): Cleanup;
 }

package/dist/channel.js

@@ -20,6 +20,6 @@ class ServerChannel extends Events {
 }
 function message(value) {
     const raw = value;
-    return { from: endpoint(raw.from), payload: raw.payload };
+    return { from: raw.from ? endpoint(raw.from) : null, payload: raw.payload };
 }
 export const channel = new ServerChannel();

package/dist/domain.d.ts

@@ -7,7 +7,7 @@ export interface HandleAddress {
     identity: string;
     reference: string;
 }
-/** Client-safe Program data transported by the authoritative host. */
+/** Client-safe Program data transported by the authoritative system. */
 export interface EndpointDeclarationRecord {
     start: boolean;
 }

package/dist/domain.js

@@ -91,7 +91,7 @@ class ProgramHandle extends ProgramBase {
 function programCommandChunk(value) {
     const chunk = value;
     if (!chunk || (chunk.stream !== "stdout" && chunk.stream !== "stderr") || typeof chunk.text !== "string") {
-        throw new Error("The host returned an invalid Program command chunk");
+        throw new Error("The system returned an invalid Program command chunk");
     }
     return Object.freeze({ stream: chunk.stream, text: chunk.text });
 }
@@ -415,7 +415,7 @@ export function lifecycleEndpoint(record, kind) {
         return owner.server;
     if (kind === "client")
         return owner.client;
-    throw new Error("The host returned an invalid Endpoint lifecycle event");
+    throw new Error("The system returned an invalid Endpoint lifecycle event");
 }
 export function exit(code, signal) {
     const namedSignal = stringOrNull(signal);

package/dist/main.d.ts

@@ -1,9 +1,9 @@
-export { host, type Host, type HostProcess, type HostProgram, type ClientDescription, type ProcessHostEvents, type ProcessHostExit, type ProgramHostEvents, type ProgramHostUninstall, type ProgramDescription, type ServerDescription } from "./host.js";
+export { system, type System, type SystemProcess, type SystemProgram, type ClientDescription, type SystemProcessEvents, type SystemProcessExit, type SystemProgramEvents, type SystemProgramUninstall, type ProgramDescription, type ServerDescription } from "./system.js";
 export { current, type Current, type CurrentClient } from "./current.js";
-export { type Answerer, type Channel } from "./channel.js";
+export { type Answerer, type Channel, type ChannelCapture, type ChannelEvents, type ChannelMessage } from "./channel.js";
 export { type ProgramStartup } from "./startup.js";
 export { type Storage } from "./storage.js";
 export { ClientServiceHandler, ServerServiceHandler } from "./service.js";
 export { ServiceHandler, type ClientServiceChannel, type ServerServiceChannel, type ServiceChannel, type ServiceKey, type ServiceLifecycleEvents } from "@phreshos/core";
 export { Client, Endpoint, Process, Program, Server, type Window, type ProgramProcess } from "./domain.js";
-export type { AnswerCapture, AnswerMessage, AnswerObserver, Askable, AskCapture, AskMessage, AskObserver, Capture, Captures, ChannelCapture, ChannelEvents, ChannelMessage, ClientTraffic, ClientDeclaration, Cleanup, DirectoryStat, EndpointDeclaration, EndpointTraffic, EntryStat, EventMessage, EventName, EventObserver, EventOptions, EventSubscriber, Exit, FileStat, Launch, LaunchClient, Layer, LogKind, LogRecord, LogSource, Message, OtherStat, Outcome, Position, ProgramEvents, ProgramPermission, ProgramProcessEvents, ProgramProcessExit, ProgramSql, ProgramStore, ProcessEvents, Publishable, ServedFile, ServerTraffic, Size, Subscribable, SubscribableEvents, SubscribableFallback, TimedAskable, TrafficCapture, TrafficEvents, TrafficMessage, Value, Theme, ThemeEvents, ThemeProperties, WallpaperLaunch, FileWallpaper, DesktopWallpaper, WritableTheme, WindowEvents, WindowGeometry, WindowLayer, WindowState } from "@phreshos/core";
+export type { AnswerCapture, AnswerMessage, AnswerObserver, Askable, AskCapture, AskMessage, AskObserver, Capture, Captures, ClientTraffic, ClientDeclaration, Cleanup, DirectoryStat, EndpointDeclaration, EndpointTraffic, EntryStat, EventMessage, EventName, EventObserver, EventOptions, EventSubscriber, Exit, FileStat, Launch, LaunchClient, Layer, LogKind, LogRecord, LogSource, Message, OtherStat, Outcome, Position, ProgramEvents, ProgramPermission, ProgramProcessEvents, ProgramProcessExit, ProgramSql, ProgramStore, ProcessEvents, Publishable, SystemUploads, Upload, ServerTraffic, Size, Subscribable, SubscribableEvents, SubscribableFallback, TimedAskable, TrafficCapture, TrafficEvents, TrafficMessage, Value, Appearance, AppearanceEvents, AppearanceSource, AppearanceSurface, ThemedValue, WritableAppearance, WindowEvents, WindowGeometry, WindowLayer, WindowState } from "@phreshos/core";

package/dist/main.js

@@ -1,4 +1,4 @@
-export { host } from "./host.js";
+export { system } from "./system.js";
 export { current } from "./current.js";
 export {} from "./channel.js";
 export {} from "./startup.js";

package/dist/storage.d.ts

@@ -7,7 +7,7 @@ export interface Storage extends CoreStorage {
 /** Server-local implementation of one Program-owned filesystem area. */
 export declare function area(program: HandleAddress, which: "data" | "cache"): Storage;
 /** Server-local access to the native home directory supplied by the System. */
-export declare function hostStorage(): Storage;
+export declare function systemStorage(): Storage;
 export declare function store(program: HandleAddress): ProgramStore;
 export declare function sql(kind: "database" | "logs", program: HandleAddress): ProgramSql;
 export declare function content(value: unknown): {

package/dist/storage.js

@@ -13,7 +13,7 @@ export function area(program, which) {
     }, `this Program's ${which}`);
 }
 /** Server-local access to the native home directory supplied by the System. */
-export function hostStorage() {
+export function systemStorage() {
     return createStorage(async function () {
         const answer = await wire.request(["host-storage", "path"]);
         return answer[0];
@@ -25,7 +25,7 @@ function createStorage(root, label) {
         if (!resolvedRoot) {
             const resolving = root().then(value => {
                 if (!isAbsolute(value))
-                    throw new Error("The host returned an invalid Storage directory");
+                    throw new Error("The system returned an invalid Storage directory");
                 return value;
             });
             const retained = resolving.catch(error => {

package/dist/{host.d.ts → system.d.ts}

@@ -1,4 +1,4 @@
-import type { DesktopWallpaper, Exit, FileWallpaper, Layer, Position, ServedFile, ServiceKey, Size, Subscribable, ThemeProperties, WritableTheme } from "@phreshos/core";
+import type { Exit, Layer, Position, ServiceKey, Size, Subscribable, SystemUploads, WritableAppearance } from "@phreshos/core";
 import type { ClientServiceHandler, ServerServiceHandler } from "./service.js";
 import { type Client, type Process, type Program, type Server } from "./domain.js";
 import { type Storage } from "./storage.js";
@@ -59,19 +59,19 @@ export type ProgramDescription = Description & (Readonly<{
     client: ClientDescription;
 }>);
 /** An uninstall reported with the affected Program and removal scope. */
-export type ProgramHostUninstall = Readonly<{
+export type SystemProgramUninstall = Readonly<{
     /** Program that left the installed state. */
     program: Program;
     /** Whether all installed resources, including storage, were removed. */
     everythingRemoved: boolean;
 }>;
 /** A Process exit reported with the Process that ended. */
-export type ProcessHostExit = Exit & Readonly<{
+export type SystemProcessExit = Exit & Readonly<{
     /** Process that ended. */
     process: Process;
 }>;
-/** Authoritative lifecycle events visible to the Server host. */
-export type ProgramHostEvents = {
+/** Authoritative lifecycle events visible to the Server system. */
+export type SystemProgramEvents = {
     /** A Program entered the runtime registry. */
     create: Program;
     /** A Program left the runtime registry. */
@@ -79,10 +79,10 @@ export type ProgramHostEvents = {
     /** A Program entered the installed state. */
     install: Program;
     /** A Program left the installed state. */
-    uninstall: ProgramHostUninstall;
+    uninstall: SystemProgramUninstall;
 };
-/** Authoritative Process lifecycle events visible to the Server host. */
-export type ProcessHostEvents = {
+/** Authoritative Process lifecycle events visible to the Server system. */
+export type SystemProcessEvents = {
     /** One Process Endpoint entered a new live incarnation. */
     endpointStart: Server | Client;
     /** One Process Endpoint incarnation ended. */
@@ -90,31 +90,29 @@ export type ProcessHostEvents = {
     /** A Process entered the runtime set. */
     create: Process;
     /** A Process left the runtime set. */
-    exit: ProcessHostExit;
+    exit: SystemProcessExit;
 };
 /** Authoritative Program registry available to a Server endpoint. */
-export interface HostProgram extends Subscribable<ProgramHostEvents, never> {
+export interface SystemProgram extends Subscribable<SystemProgramEvents, never> {
     list(onlyInstalled?: boolean): Promise<Program[]>;
     find(identity: string): Promise<Program | null>;
     create(source: ProgramDescription | string): Promise<Program>;
 }
 /** Authoritative Process registry available to a Server endpoint. */
-export interface HostProcess extends Subscribable<ProcessHostEvents, never> {
+export interface SystemProcess extends Subscribable<SystemProcessEvents, never> {
     list(): Promise<Process[]>;
     find(identity: string): Promise<Process | null>;
 }
 /** Authoritative system capabilities available to a Server endpoint. */
-export interface Host {
+export interface System {
     /** Native operating-system home storage available to Server endpoints. */
     readonly storage: Storage;
-    /** Observable system Theme authority. */
-    readonly theme: WritableTheme<ThemeProperties>;
-    /** Authoritative wallpaper visible before authentication. */
-    readonly signInWallpaper: FileWallpaper;
-    /** Authoritative wallpaper visible within authenticated desktops. */
-    readonly desktopWallpaper: DesktopWallpaper;
-    readonly program: HostProgram;
-    readonly process: HostProcess;
+    /** Complete unresolved Appearance authority owned by the System. */
+    readonly appearance: WritableAppearance;
+    readonly program: SystemProgram;
+    readonly process: SystemProcess;
+    /** Flat System-owned public uploads capability. */
+    readonly uploads: SystemUploads;
     /** Returns a stable handle for one exact Service identity. */
     service<ServiceEvents extends object = {}>(key: ServiceKey & {
         endpoint: "server";
@@ -122,9 +120,7 @@ export interface Host {
     service<ServiceEvents extends object = {}>(key: ServiceKey & {
         endpoint: "client";
     }): ClientServiceHandler<ServiceEvents>;
-    /** Publishes a value through the host and returns its public file metadata. */
-    serve(value: unknown): Promise<ServedFile>;
 }
 /** Authoritative system capabilities for the currently executing Server. */
-export declare const host: Host;
+export declare const system: System;
 export {};

package/dist/{host.js → system.js}

@@ -1,26 +1,23 @@
 import Events from "./events.js";
 import { exit, lifecycleEndpoint, process, program } from "./domain.js";
-import serve from "./served.js";
-import ServerTheme from "./theme.js";
-import { ServerDesktopWallpaper, ServerSignInWallpaper } from "./wallpaper.js";
+import { uploads } from "./uploads.js";
+import ServerAppearance from "./appearance.js";
 import wire from "./wire.js";
 import { prepareService } from "./service.js";
-import { hostStorage } from "./storage.js";
-class ServerHost {
-    storage = hostStorage();
-    theme = new ServerTheme();
-    signInWallpaper = new ServerSignInWallpaper();
-    desktopWallpaper = new ServerDesktopWallpaper();
-    program = new ServerHostProgram();
-    process = new ServerHostProcess();
+import { systemStorage } from "./storage.js";
+class ServerSystem {
+    storage = systemStorage();
+    appearance = new ServerAppearance();
+    program = new ServerSystemProgram();
+    process = new ServerSystemProcess();
+    uploads = uploads;
     service(key) { return prepareService(key); }
-    serve(value) { return serve(value); }
 }
-class ServerHostProgram extends Events {
+class ServerSystemProgram extends Events {
     constructor() {
-        super((event, listener, impossible) => wire.on("host-program", event, (...values) => listener(hostProgramEvent(event, values)), null, impossible), observer => wire.onAll("host-program", (event, ...values) => {
+        super((event, listener, impossible) => wire.on("host-program", event, (...values) => listener(systemProgramEvent(event, values)), null, impossible), observer => wire.onAll("host-program", (event, ...values) => {
             if (typeof event === "string")
-                observer(event, hostProgramEvent(event, values));
+                observer(event, systemProgramEvent(event, values));
         }));
     }
     async list(onlyInstalled = false) {
@@ -36,11 +33,11 @@ class ServerHostProgram extends Events {
         return program(answer[0]);
     }
 }
-class ServerHostProcess extends Events {
+class ServerSystemProcess extends Events {
     constructor() {
-        super((event, listener, impossible) => wire.on("host-process", event, (...values) => listener(hostProcessEvent(event, values)), null, impossible), observer => wire.onAll("host-process", (event, ...values) => {
+        super((event, listener, impossible) => wire.on("host-process", event, (...values) => listener(systemProcessEvent(event, values)), null, impossible), observer => wire.onAll("host-process", (event, ...values) => {
             if (typeof event === "string")
-                observer(event, hostProcessEvent(event, values));
+                observer(event, systemProcessEvent(event, values));
         }));
     }
     async list() {
@@ -52,7 +49,7 @@ class ServerHostProcess extends Events {
         return answer[0] ? process(answer[0]) : null;
     }
 }
-function hostProcessEvent(event, values) {
+function systemProcessEvent(event, values) {
     if (event === "endpointStart" || event === "endpointStop")
         return lifecycleEndpoint(values[1], values[2]);
     if (event === "create") {
@@ -63,7 +60,7 @@ function hostProcessEvent(event, values) {
     }
     return values[0];
 }
-function hostProgramEvent(event, values) {
+function systemProgramEvent(event, values) {
     if (event === "create" || event === "forget" || event === "install") {
         return program(values[1]);
     }
@@ -73,4 +70,4 @@ function hostProgramEvent(event, values) {
     return values[0];
 }
 /** Authoritative system capabilities for the currently executing Server. */
-export const host = new ServerHost();
+export const system = new ServerSystem();

package/dist/uploads.d.ts

@@ -0,0 +1,14 @@
+import { type SystemUploads, type Upload } from "@phreshos/core";
+/** Flat upload access performed locally by a Server Endpoint. */
+declare class ServerUploads implements SystemUploads {
+    private accessPromise;
+    write(value: unknown): Promise<Upload>;
+    stream(file: string): Promise<ReadableStream<Uint8Array>>;
+    bytes(file: string): Promise<Uint8Array<ArrayBuffer>>;
+    text(file: string): Promise<string>;
+    json<Value>(file: string): Promise<Value>;
+    stat(file: string): Promise<Upload | null>;
+    private access;
+}
+export declare const uploads: ServerUploads;
+export {};

package/dist/uploads.js

@@ -0,0 +1,84 @@
+import { isUploadFile } from "@phreshos/core";
+import { randomUUID } from "node:crypto";
+import { createReadStream, createWriteStream, mkdirSync } from "node:fs";
+import { rename, rm } from "node:fs/promises";
+import { join } from "node:path";
+import { Readable } from "node:stream";
+import { pipeline } from "node:stream/promises";
+import { content } from "./storage.js";
+import wire from "./wire.js";
+/** Flat upload access performed locally by a Server Endpoint. */
+class ServerUploads {
+    accessPromise = null;
+    async write(value) {
+        const access = await this.access();
+        const source = content(value);
+        const identity = randomUUID();
+        const file = `${identity}.${source.extension}`;
+        const temporary = join(access.root, `.${identity}.uploading`);
+        const destination = join(access.root, file);
+        let size = 0;
+        mkdirSync(access.root, { recursive: true });
+        try {
+            await pipeline(Readable.fromWeb(source.stream), async function* (chunks) {
+                for await (const chunk of chunks) {
+                    size += chunk.byteLength;
+                    if (size > access.limit)
+                        throw new Error(`The upload exceeds ${access.limit / 1024 / 1024 / 1024} GB`);
+                    yield chunk;
+                }
+            }, createWriteStream(temporary, { flags: "wx" }));
+            await rename(temporary, destination);
+        }
+        catch (error) {
+            await rm(temporary, { force: true }).catch(() => undefined);
+            throw error;
+        }
+        const upload = await this.stat(file);
+        if (!upload)
+            throw new Error("The completed upload could not be described");
+        return upload;
+    }
+    async stream(file) {
+        requireFile(file);
+        const { root } = await this.access();
+        return Readable.toWeb(createReadStream(join(root, file)));
+    }
+    async bytes(file) {
+        return new Uint8Array(await new Response(await this.stream(file)).arrayBuffer());
+    }
+    async text(file) {
+        return new Response(await this.stream(file)).text();
+    }
+    async json(file) {
+        return JSON.parse(await this.text(file));
+    }
+    async stat(file) {
+        requireFile(file);
+        const answer = await wire.request(["uploads", "stat", file]);
+        return answer[0];
+    }
+    access() {
+        if (!this.accessPromise) {
+            const resolving = wire.request(["uploads", "access"]).then(answer => {
+                const [root, limit] = answer;
+                if (typeof root !== "string" || !root || typeof limit !== "number" || !Number.isFinite(limit) || limit <= 0) {
+                    throw new Error("The System returned invalid upload access");
+                }
+                return { root, limit };
+            });
+            const retained = resolving.catch(error => {
+                if (this.accessPromise === retained)
+                    this.accessPromise = null;
+                throw error;
+            });
+            this.accessPromise = retained;
+        }
+        return this.accessPromise;
+    }
+}
+function requireFile(file) {
+    if (!isUploadFile(file))
+        throw new Error("That is not an upload file");
+}
+export const uploads = new ServerUploads();

package/dist/wire.d.ts

@@ -18,7 +18,7 @@ declare class Wire {
     send(route: string, ...values: unknown[]): void;
     request(values: unknown[], timeout?: number): Promise<unknown>;
     requestWithin(values: unknown[], deadline: Deadline): Promise<unknown>;
-    /** Opens one long-running host operation and yields its ordered values. */
+    /** Opens one long-running system operation and yields its ordered values. */
     stream(values: unknown[], timeout?: number): AsyncIterableIterator<unknown>;
     /** Resolves this endpoint's Process address only for operations that need it. */
     identity(): Promise<{

package/dist/wire.js

@@ -71,7 +71,7 @@ class Wire {
             this.send("end-host", "wait", question, ...values);
         });
     }
-    /** Opens one long-running host operation and yields its ordered values. */
+    /** Opens one long-running system operation and yields its ordered values. */
     stream(values, timeout = defaultTimeout) {
         const wire = this;
         return (async function* () {
@@ -117,7 +117,7 @@ class Wire {
             const resolving = this.request(["current-process"]).then(value => {
                 const [record] = value;
                 if (typeof record?.identity !== "string" || typeof record.reference !== "string") {
-                    throw new Error("The host returned an invalid Process identity");
+                    throw new Error("The system returned an invalid Process identity");
                 }
                 return { process: record.identity, reference: record.reference };
             });
@@ -315,7 +315,7 @@ class Wire {
         }
         else if (operation === "data") {
             if (stream.queue.length >= maximumStreamQueue) {
-                stream.failure = new Error(`Host stream queue exceeded its capacity of ${maximumStreamQueue}`);
+                stream.failure = new Error(`System stream queue exceeded its capacity of ${maximumStreamQueue}`);
             }
             else {
                 stream.queue.push(value);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@phreshos/server",
-  "version": "0.1.17",
+  "version": "0.1.19",
   "description": "The SDK used by a Program's server endpoint.",
   "type": "module",
   "main": "dist/main.js",
@@ -46,13 +46,13 @@
     "prepack": "node --run build"
   },
   "peerDependencies": {
-    "@phreshos/core": "^0.1.14"
+    "@phreshos/core": "^0.1.17"
   },
   "dependencies": {
     "@msgpack/msgpack": "^3.1.3"
   },
   "devDependencies": {
-    "@phreshos/core": "^0.1.14",
+    "@phreshos/core": "^0.1.18",
     "@types/node": "^26.2.0",
     "typescript": "^6.0.3"
   }

package/dist/served.d.ts

@@ -1,3 +0,0 @@
-import type { ServedFile } from "@phreshos/core";
-/** Writes one public value directly into the host-managed served-file area. */
-export default function serve(value: unknown): Promise<ServedFile>;

package/dist/served.js

@@ -1,41 +0,0 @@
-import { randomUUID } from "node:crypto";
-import { createWriteStream, mkdirSync, statSync } from "node:fs";
-import { rename, rm } from "node:fs/promises";
-import { join } from "node:path";
-import { Readable } from "node:stream";
-import { pipeline } from "node:stream/promises";
-import { content } from "./storage.js";
-import wire from "./wire.js";
-/** Writes one public value directly into the host-managed served-file area. */
-export default async function serve(value) {
-    const answer = await wire.request(["serve"]);
-    const [root, limit] = answer;
-    const source = content(value);
-    const identity = randomUUID();
-    const file = `${identity}.${source.extension}`;
-    const temporary = join(root, `.${identity}.serving`);
-    const destination = join(root, file);
-    let size = 0;
-    mkdirSync(root, { recursive: true });
-    try {
-        await pipeline(Readable.fromWeb(source.stream), async function* (chunks) {
-            for await (const chunk of chunks) {
-                size += chunk.byteLength;
-                if (size > limit)
-                    throw new Error(`The served value exceeds ${limit / 1024 / 1024 / 1024} GB`);
-                yield chunk;
-            }
-        }, createWriteStream(temporary, { flags: "wx" }));
-        await rename(temporary, destination);
-    }
-    catch (error) {
-        await rm(temporary, { force: true }).catch(() => undefined);
-        throw error;
-    }
-    return {
-        file,
-        type: source.type,
-        size,
-        time: Math.round(statSync(destination).mtimeMs)
-    };
-}

package/dist/theme.d.ts

@@ -1,15 +0,0 @@
-import { type ThemeProperties } from "@phreshos/core";
-import Events from "./events.js";
-/** System Theme authority reached explicitly through the server boundary. */
-export default class ServerTheme extends Events {
-    constructor();
-    snapshot(): Promise<Readonly<{
-        background: string;
-        foreground: string;
-        accent: string;
-        spacing: number;
-        radius: number;
-        surface: import("@phreshos/core").ThemeSurface;
-    }>>;
-    readonly update: (theme: ThemeProperties) => Promise<void>;
-}

package/dist/theme.js

@@ -1,21 +0,0 @@
-import { createThemeSnapshot } from "@phreshos/core";
-import Events from "./events.js";
-import wire from "./wire.js";
-/** System Theme authority reached explicitly through the server boundary. */
-export default class ServerTheme extends Events {
-    constructor() {
-        super((event, listener, impossible) => wire.on("host-theme", event, value => {
-            listener(createThemeSnapshot(value));
-        }, null, impossible), observer => wire.onAll("host-theme", (event, value) => {
-            if (typeof event === "string")
-                observer(event, createThemeSnapshot(value));
-        }));
-    }
-    async snapshot() {
-        const [theme] = await wire.request(["theme"]);
-        return createThemeSnapshot(theme);
-    }
-    update = async (theme) => {
-        await wire.request(["update-theme", theme]);
-    };
-}

package/dist/wallpaper.d.ts

@@ -1,18 +0,0 @@
-import type { DesktopWallpaper, FileWallpaper, WallpaperLaunch } from "@phreshos/core";
-import { type Program } from "./domain.js";
-declare class ServerFileWallpaper implements FileWallpaper {
-    private readonly surface;
-    constructor(surface: "sign-in" | "desktop");
-    set(file: string): Promise<void>;
-    remove(): Promise<void>;
-}
-/** Authoritative sign-in wallpaper control available to Server endpoints. */
-export declare class ServerSignInWallpaper extends ServerFileWallpaper {
-    constructor();
-}
-/** Authoritative desktop wallpaper control available to Server endpoints. */
-export declare class ServerDesktopWallpaper extends ServerFileWallpaper implements DesktopWallpaper {
-    constructor();
-    setProgram(program: Program, launch?: WallpaperLaunch): Promise<void>;
-}
-export {};

package/dist/wallpaper.js

@@ -1,25 +0,0 @@
-import { programAddress } from "./domain.js";
-import wire from "./wire.js";
-class ServerFileWallpaper {
-    surface;
-    constructor(surface) {
-        this.surface = surface;
-    }
-    async set(file) {
-        await wire.request(["wallpaper", this.surface, "set", file]);
-    }
-    async remove() {
-        await wire.request(["wallpaper", this.surface, "remove"]);
-    }
-}
-/** Authoritative sign-in wallpaper control available to Server endpoints. */
-export class ServerSignInWallpaper extends ServerFileWallpaper {
-    constructor() { super("sign-in"); }
-}
-/** Authoritative desktop wallpaper control available to Server endpoints. */
-export class ServerDesktopWallpaper extends ServerFileWallpaper {
-    constructor() { super("desktop"); }
-    async setProgram(program, launch = {}) {
-        await wire.request(["wallpaper", "desktop", "set-program", programAddress(program), launch]);
-    }
-}