@phreshos/server 0.1.10 → 0.1.12

package/README.md

@@ -113,9 +113,47 @@ waiter.
 Server Program handles add `install()` and `fork()`. Their filesystem areas
 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.createProgram()` therefore require an
+Object descriptions passed to `host.program.create()` therefore require an
 explicit absolute storage root as well as at least one declared Endpoint.
 
+Host registries are separated by owner. Reads, commands, and the complete
+subscription contract live on their relevant capability rather than directly
+on `host`:
+
+```ts
+const programs = await host.program.list()
+const program = await host.program.find("counter")
+const processes = await host.process.list()
+
+const stopPrograms = host.program.subscribe("create", value => undefined)
+const stopProcesses = host.process.subscribe("exit", value => undefined)
+```
+
+A Program owns its scoped Process capability:
+
+```ts
+const processes = await program.process.list()
+const process = await program.process.find("worker")
+const created = await program.process.create({ name: "worker" })
+const shared = await program.process.findOrCreate({
+  name: "shared-server",
+  server: true,
+  client: false
+})
+```
+
+`findOrCreate()` is atomic at the authoritative Core. Concurrent equivalent
+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
+handler exposes its authored `name`, `enabled()`, `waitReady()`, lifecycle
+subscriptions, and channel; it does not expose its Program or Endpoint as
+separate fields. Services are not a second public registry: inspect Programs
+and their Endpoint declarations. `program.server?.hasService()` identifies a
+declared Service capability, while `await program.server?.docs()` reads its
+installed policy and API documentation before the Endpoint starts.
+
 `program.icon()` requests a guaranteed PNG `Blob` in `small`, `medium`, or
 `large` form without exposing the Program's source path or the system's private
 asset-hosting address. Omitting the size selects `medium`.
@@ -137,6 +175,6 @@ await program.startup.disable()
 ```
 
 The system validates this through the same launch contract as
-`createProcess()`. Setting startup does not create a Process immediately.
+`program.process.create()`. Setting startup does not create a Process immediately.
 `uninstall(false)` preserves the configuration but makes it inactive until the
 Program is installed again; removing everything deletes it.

package/dist/channel.d.ts

@@ -1,9 +1,9 @@
-import type { Channel as CoreChannel, ChannelMessage, Cleanup, ServerServiceDefinition } from "@phreshos/core";
+import type { Channel as CoreChannel, ChannelMessage, Cleanup } from "@phreshos/core";
 import { type Endpoint } from "./domain.js";
 /** Handles one question addressed to the current Server. */
 export type Answerer<Payload = unknown, Result = undefined> = (message: ChannelMessage<Payload>) => Result | Promise<Result>;
 /** Events and questions explicitly accepted by the current Server. */
-export interface Channel<Events extends object = {}> extends CoreChannel<Events, Endpoint, ServerServiceDefinition> {
+export interface Channel<Events extends object = {}> extends CoreChannel<Events, Endpoint> {
     /** Registers one answerer; omitting its return produces `undefined`. */
     answer<Payload = unknown, Result = undefined>(event: string, answerer: Answerer<Payload, Result>): Cleanup;
 }

package/dist/channel.js

@@ -12,7 +12,7 @@ class ServerChannel extends Events {
     publish(event, payload = undefined) {
         wire.send("end-host", "emit", event, payload);
     }
-    async enableService(definition) { await enableCurrentService(definition); }
+    async enableService(name) { await enableCurrentService(name); }
     async disableService() { await disableCurrentService(); }
     answer(event, answerer) {
         return wire.answer("end-end", event, value => answerer(message(value)));

package/dist/current.js

@@ -31,7 +31,7 @@ let ownerPromise = null;
 let currentClient;
 function owner() {
     if (!ownerPromise) {
-        const resolving = wire.request(["process"]).then(answer => {
+        const resolving = wire.request(["current-process"]).then(answer => {
             return process(answer[0], { client: currentClient });
         });
         const retained = resolving.catch(error => {
@@ -58,7 +58,7 @@ class ServerCurrent {
         return answer[0] ? process(answer[0]) : null;
     }
     async program() {
-        const answer = await wire.request(["program"]);
+        const answer = await wire.request(["current-program"]);
         return program(answer[0]);
     }
     async option(name) {

package/dist/domain.d.ts

@@ -1,4 +1,4 @@
-import { Client as CoreClient, Endpoint as CoreEndpoint, Process as CoreProcess, Program as CoreProgram, Server as CoreServer, type AnswerCapture, type AskCapture, type Cleanup, type ClientDeclaration, type EndpointDeclaration, type Exit, type Launch, type ProgramPermissions, type ProgramArea as CoreProgramArea, type TrafficMessage, type Window as CoreWindow, type WindowState } from "@phreshos/core";
+import { Client as CoreClient, Endpoint as CoreEndpoint, Process as CoreProcess, Program as CoreProgram, Server as CoreServer, type AnswerCapture, type AskCapture, type Cleanup, type ClientDeclaration, type Exit, type Launch, type Position, type ProgramPermission, type ProgramProcess as CoreProgramProcess, type ProgramArea as CoreProgramArea, type Size, type TrafficMessage, type Window as CoreWindow, type WindowState } from "@phreshos/core";
 import Events from "./events.js";
 import { type ProgramStartup } from "./startup.js";
 export interface HandleAddress {
@@ -13,6 +13,17 @@ export interface ProgramArea extends CoreProgramArea {
     resolve(...path: string[]): Promise<string>;
 }
 /** Client-safe Program data transported by the authoritative host. */
+export interface EndpointDeclarationRecord {
+    start: boolean;
+    hasService: boolean;
+}
+export interface ClientDeclarationRecord extends EndpointDeclarationRecord {
+    title: string | null;
+    size: Size | null;
+    position: Position | null;
+    layer: ClientDeclaration["layer"];
+    minimize: boolean | null;
+}
 export interface ProgramRecord {
     reference: string;
     identity: string;
@@ -20,8 +31,8 @@ export interface ProgramRecord {
     name: string;
     version: string | null;
     description: string | null;
-    server: EndpointDeclaration | null;
-    client: ClientDeclaration | null;
+    server: EndpointDeclarationRecord | null;
+    client: ClientDeclarationRecord | null;
 }
 /** Process data transported with every Endpoint reference. */
 export interface ProcessRecord {
@@ -40,7 +51,7 @@ export interface EndpointReference {
 }
 export type WindowRecord = WindowState;
 /** Server-visible Program handle and privileged Program operations. */
-export interface Program<Events extends object = {}> extends CoreProgram<Events> {
+export interface Program<Events extends object = {}> extends Omit<CoreProgram<Events>, "process"> {
     /** Persistent filesystem data shared by every Process of this Program. */
     readonly data: ProgramArea;
     /** Disposable filesystem data shared by every Process of this Program. */
@@ -48,21 +59,30 @@ export interface Program<Events extends object = {}> extends CoreProgram<Events>
     /** Persistent Process launch used when the system starts. */
     readonly startup: ProgramStartup;
     /** Persistent permission decisions owned by this Program. */
-    readonly permissions: ProgramPermissions;
+    readonly permission: ProgramPermission;
+    /** Operations and lifecycle observation for this Program's Processes. */
+    readonly process: ProgramProcess;
+    /** Installs this Program and returns the same handle. */
+    install(): Promise<this>;
+    /** Creates a new runtime Program with the supplied stable identity. */
+    fork(identity: string): Promise<Program>;
+}
+/** Server-visible Process operations scoped to one Program. */
+export interface ProgramProcess extends Omit<CoreProgramProcess, "list" | "first" | "last" | "find" | "create" | "findOrCreate"> {
     /** Returns every live Process of this Program. */
-    processes(): Promise<Process[]>;
+    list(): Promise<Process[]>;
     /** Returns the earliest-started live Process, or `null` when none exist. */
-    firstProcess(): Promise<Process | null>;
+    first(): Promise<Process | null>;
     /** Returns the latest-started live Process, or `null` when none exist. */
-    lastProcess(): Promise<Process | null>;
+    last(): Promise<Process | null>;
     /** Finds a live Process by runtime identity or Program-local name. */
-    getProcess(identityOrName: string): Promise<Process | null>;
+    find(identityOrName: string): Promise<Process | null>;
     /** Creates one Process of this Program. */
-    createProcess(launch?: Launch): Promise<Process>;
-    /** Installs this Program and returns the same handle. */
-    install(): Promise<this>;
-    /** Creates a new runtime Program with the supplied stable identity. */
-    fork(identity: string): Promise<Program>;
+    create(launch?: Launch): Promise<Process>;
+    /** Finds the named Process or atomically creates it with the same resolved launch. */
+    findOrCreate(launch: Launch & Readonly<{
+        name: string;
+    }>): Promise<Process>;
 }
 /** Server-visible Process handle. */
 export interface Process<Events extends object = {}> extends CoreProcess<Events> {

package/dist/domain.js

@@ -5,7 +5,7 @@ import Deadline from "./deadline.js";
 import HandleRegistry from "./handle-registry.js";
 import { area, sql, store } from "./storage.js";
 import startup, {} from "./startup.js";
-import permissions from "./permissions.js";
+import permission from "./permissions.js";
 import wire from "./wire.js";
 import { endpointService } from "./service.js";
 const handles = new HandleRegistry();
@@ -22,7 +22,8 @@ class ProgramHandle extends ProgramBase {
     logs;
     database;
     startup;
-    permissions;
+    permission;
+    process;
     record;
     constructor(record) {
         super();
@@ -35,38 +36,25 @@ class ProgramHandle extends ProgramBase {
         this.logs = sql("logs", this.address);
         this.database = sql("database", this.address);
         this.startup = startup(this.address);
-        this.permissions = permissions(this.address);
-        bindEvents(this, scoped("host-end", record.reference, programEvent));
+        this.permission = permission(this.address);
+        this.process = new ProgramProcessHandle(this.address, record.reference);
+        bindEvents(this, scoped("program-host", record.reference, programEvent));
     }
     get name() { return this.record.name; }
     get version() { return this.record.version; }
     get description() { return this.record.description; }
-    get server() { return this.record.server; }
-    get client() { return this.record.client; }
+    get server() {
+        return this.record.server ? declaration(this.address, "server", this.record.server) : null;
+    }
+    get client() {
+        return this.record.client ? clientDeclaration(this.address, this.record.client) : null;
+    }
     get address() { return { identity: this.identity, reference: this.reference }; }
     update(record) {
         if (record.reference !== this.reference)
             throw new Error("A Program handle cannot become another Program");
         this.record = record;
     }
-    async processes() {
-        const answer = await wire.request(["processes", this.address]);
-        return answer[0].map(record => process(record));
-    }
-    async firstProcess() {
-        return chronological(await this.processes())[0] ?? null;
-    }
-    async lastProcess() {
-        return chronological(await this.processes()).at(-1) ?? null;
-    }
-    async getProcess(identityOrName) {
-        const answer = await wire.request(["program-process", this.address, identityOrName]);
-        return answer[0] ? process(answer[0]) : null;
-    }
-    async createProcess(launch = {}) {
-        const answer = await wire.request(["create-process", this.address, launch]);
-        return process(answer[0]);
-    }
     async icon(size = "medium") {
         const answer = await wire.request(["icon", this.address, size]);
         return new Blob([Uint8Array.from(answer[0])], { type: "image/png" });
@@ -89,8 +77,60 @@ class ProgramHandle extends ProgramBase {
     async forget() {
         await wire.request(["forget", this.address]);
     }
+}
+function declaration(address, endpoint, record) {
+    return Object.freeze({
+        start: record.start,
+        hasService: () => record.hasService,
+        docs: () => endpointDocs(address, endpoint, record.hasService)
+    });
+}
+function clientDeclaration(address, record) {
+    return Object.freeze({
+        ...declaration(address, "client", record),
+        title: record.title,
+        size: record.size,
+        position: record.position,
+        layer: record.layer,
+        minimize: record.minimize
+    });
+}
+async function endpointDocs(address, endpoint, declared) {
+    if (!declared)
+        return null;
+    const answer = await wire.request(["endpoint-docs", address, endpoint]);
+    return answer[0];
+}
+class ProgramProcessHandle {
+    address;
+    constructor(address, reference) {
+        this.address = address;
+        bindEvents(this, scoped("program-process", reference, programProcessEvent));
+    }
+    async list() {
+        const answer = await wire.request(["program-process-list", this.address]);
+        return answer[0].map(record => process(record));
+    }
+    async first() {
+        return chronological(await this.list())[0] ?? null;
+    }
+    async last() {
+        return chronological(await this.list()).at(-1) ?? null;
+    }
+    async find(identityOrName) {
+        const answer = await wire.request(["program-process-find", this.address, identityOrName]);
+        return answer[0] ? process(answer[0]) : null;
+    }
+    async create(launch = {}) {
+        const answer = await wire.request(["program-process-create", this.address, launch]);
+        return process(answer[0]);
+    }
+    async findOrCreate(launch) {
+        const answer = await wire.request(["program-process-find-or-create", this.address, launch]);
+        return process(answer[0]);
+    }
     async exitAll() {
-        const answer = await wire.request(["exit-all", this.address]);
+        const answer = await wire.request(["program-process-exit-all", this.address]);
         return answer[0];
     }
 }
@@ -339,13 +379,16 @@ function unscoped(subject, values) {
         return values;
     return values[0] === subject ? values.slice(1) : null;
 }
-function programEvent(event, values) {
+function programProcessEvent(event, values) {
     if (event === "endpointStart" || event === "endpointStop")
         return lifecycleEndpoint(values[0], values[1]);
-    if (event === "processCreate")
+    if (event === "create")
         return process(values[0]);
-    if (event === "processExit")
+    if (event === "exit")
         return { process: process(values[0]), ...exit(values[1], values[2]) };
+    return undefined;
+}
+function programEvent(event, values) {
     if (event === "uninstall")
         return { everythingRemoved: values[0] === true };
     return undefined;

package/dist/host.d.ts

@@ -1,4 +1,4 @@
-import type { DesktopWallpaper, Exit, FileWallpaper, Layer, Position, ServedFile, ClientServiceHandler, ServerServiceHandler, Size, Subscribable, ThemeProperties, WritableTheme } from "@phreshos/core";
+import type { DesktopWallpaper, Exit, FileWallpaper, Layer, Position, ServedFile, ClientServiceHandler, ServerServiceHandler, ServiceKey, Size, Subscribable, ThemeProperties, WritableTheme } from "@phreshos/core";
 import { type Client, type Process, type Program, type Server } from "./domain.js";
 /** Resolved production description for a Program's Server. */
 export type ServerDescription = Readonly<{
@@ -6,6 +6,8 @@ export type ServerDescription = Readonly<{
     location: string;
     /** Whether newly created Processes start this Server by default. */
     start?: boolean;
+    /** Absolute Markdown file documenting the Service this Server may expose. */
+    serviceDocs?: string;
     /** Command used to install the Server's production dependencies. */
     installCommand?: string;
     /** Command used to start the Server from its production directory. */
@@ -17,6 +19,8 @@ export type ClientDescription = Readonly<{
     location: string;
     /** Whether newly created Processes start this Client by default. */
     start?: boolean;
+    /** Absolute Markdown file documenting the Service this Client may expose. */
+    serviceDocs?: string;
     /** Default Window title. */
     title?: string;
     /** Default Window size. */
@@ -55,68 +59,69 @@ export type ProgramDescription = Description & (Readonly<{
     client: ClientDescription;
 }>);
 /** An uninstall reported with the affected Program and removal scope. */
-export type HostProgramUninstall = Readonly<{
+export type ProgramHostUninstall = 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 HostProcessExit = Exit & Readonly<{
+export type ProcessHostExit = Exit & Readonly<{
     /** Process that ended. */
     process: Process;
 }>;
 /** Authoritative lifecycle events visible to the Server host. */
-export type HostEvents = {
-    /** One Process Endpoint entered a new live incarnation. */
-    endpointStart: Server | Client;
-    /** One Process Endpoint incarnation ended. */
-    endpointStop: Server | Client;
+export type ProgramHostEvents = {
     /** A Program entered the runtime registry. */
-    programCreate: Program;
+    create: Program;
     /** A Program left the runtime registry. */
-    programForget: Program;
+    forget: Program;
     /** A Program entered the installed state. */
-    programInstall: Program;
+    install: Program;
     /** A Program left the installed state. */
-    programUninstall: HostProgramUninstall;
+    uninstall: ProgramHostUninstall;
+};
+/** Authoritative Process lifecycle events visible to the Server host. */
+export type ProcessHostEvents = {
+    /** One Process Endpoint entered a new live incarnation. */
+    endpointStart: Server | Client;
+    /** One Process Endpoint incarnation ended. */
+    endpointStop: Server | Client;
     /** A Process entered the runtime set. */
-    processCreate: Process;
+    create: Process;
     /** A Process left the runtime set. */
-    processExit: HostProcessExit;
+    exit: ProcessHostExit;
 };
+/** Authoritative Program registry available to a Server endpoint. */
+export interface HostProgram extends Subscribable<ProgramHostEvents, 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> {
+    list(): Promise<Process[]>;
+    find(identity: string): Promise<Process | null>;
+}
 /** Authoritative system capabilities available to a Server endpoint. */
-export interface Host<Events extends object = {}> extends Subscribable<HostEvents & Events, never> {
+export interface Host {
     /** 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;
-    /** Publishes a value through the host and returns its public file metadata. */
-    serve(value: unknown): Promise<ServedFile>;
-    /** Returns all known Programs, optionally restricted to installed Programs. */
-    programs(onlyInstalled?: boolean): Promise<Program[]>;
-    /** Returns the Program with the given stable identity. */
-    getProgram(identity: string): Promise<Program>;
-    /** Creates a runtime Program from a description or description file path. */
-    createProgram(source: ProgramDescription | string): Promise<Program>;
-    /** Returns every live Process known to the authoritative host. */
-    processes(): Promise<Process[]>;
-    /** Returns the live Process with the given runtime identity. */
-    getProcess(identity: string): Promise<Process>;
-    /** Returns a stable handle for one exact Server service identity. */
-    service<ServiceEvents extends object = {}>(key: {
-        program: string;
+    readonly program: HostProgram;
+    readonly process: HostProcess;
+    /** Returns a stable handle for one exact Service identity. */
+    service<ServiceEvents extends object = {}>(key: ServiceKey & {
         endpoint: "server";
-        name: string;
     }): ServerServiceHandler<ServiceEvents>;
-    /** Returns a stable handle for one exact Client service identity. */
-    service<ServiceEvents extends object = {}>(key: {
-        program: string;
+    service<ServiceEvents extends object = {}>(key: ServiceKey & {
         endpoint: "client";
-        name: string;
     }): 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;

package/dist/host.js

@@ -4,55 +4,68 @@ import serve from "./served.js";
 import ServerTheme from "./theme.js";
 import { ServerDesktopWallpaper, ServerSignInWallpaper } from "./wallpaper.js";
 import wire from "./wire.js";
-import { service as serviceHandle } from "./service.js";
-class ServerHost extends Events {
+import { prepareService } from "./service.js";
+class ServerHost {
     theme = new ServerTheme();
     signInWallpaper = new ServerSignInWallpaper();
     desktopWallpaper = new ServerDesktopWallpaper();
+    program = new ServerHostProgram();
+    process = new ServerHostProcess();
+    service(key) { return prepareService(key); }
+    serve(value) { return serve(value); }
+}
+class ServerHostProgram extends Events {
     constructor() {
-        super((event, listener, impossible) => wire.on("host-events", event, (...values) => listener(hostEvent(event, values)), null, impossible), observer => wire.onAll("host-events", (event, ...values) => {
+        super((event, listener, impossible) => wire.on("host-program", event, (...values) => listener(hostProgramEvent(event, values)), null, impossible), observer => wire.onAll("host-program", (event, ...values) => {
             if (typeof event === "string")
-                observer(event, hostEvent(event, values));
+                observer(event, hostProgramEvent(event, values));
         }));
     }
-    serve(value) { return serve(value); }
-    async programs(onlyInstalled = false) {
-        const answer = await wire.request(["programs", onlyInstalled]);
+    async list(onlyInstalled = false) {
+        const answer = await wire.request(["host-program-list", onlyInstalled]);
         return answer[0].map(program);
     }
-    async getProgram(identity) {
-        const answer = await wire.request(["program", identity]);
-        return program(answer[0]);
+    async find(identity) {
+        const answer = await wire.request(["host-program-find", identity]);
+        return answer[0] ? program(answer[0]) : null;
     }
-    async createProgram(source) {
-        const answer = await wire.request(["create-program", source]);
+    async create(source) {
+        const answer = await wire.request(["host-program-create", source]);
         return program(answer[0]);
     }
-    async processes() {
-        const answer = await wire.request(["processes"]);
-        return answer[0].map(record => process(record));
+}
+class ServerHostProcess 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) => {
+            if (typeof event === "string")
+                observer(event, hostProcessEvent(event, values));
+        }));
     }
-    async getProcess(identity) {
-        const answer = await wire.request(["process", identity]);
-        return process(answer[0]);
+    async list() {
+        const answer = await wire.request(["host-process-list"]);
+        return answer[0].map(record => process(record));
     }
-    service(key) {
-        return serviceHandle(key);
+    async find(identity) {
+        const answer = await wire.request(["host-process-find", identity]);
+        return answer[0] ? process(answer[0]) : null;
     }
 }
-function hostEvent(event, values) {
+function hostProcessEvent(event, values) {
     if (event === "endpointStart" || event === "endpointStop")
         return lifecycleEndpoint(values[1], values[2]);
-    if (event === "processCreate") {
+    if (event === "create") {
         return process(values[1]);
     }
-    if (event === "processExit") {
+    if (event === "exit") {
         return { process: process(values[1]), ...exit(values[2], values[3]) };
     }
-    if (event === "programCreate" || event === "programForget" || event === "programInstall") {
+    return values[0];
+}
+function hostProgramEvent(event, values) {
+    if (event === "create" || event === "forget" || event === "install") {
         return program(values[1]);
     }
-    if (event === "programUninstall") {
+    if (event === "uninstall") {
         return { program: program(values[1]), everythingRemoved: values[2] === true };
     }
     return values[0];

package/dist/main.d.ts

@@ -1,7 +1,7 @@
-export { host, type Host, type ClientDescription, type HostEvents, type HostProcessExit, type HostProgramUninstall, type ProgramDescription, type ServerDescription } from "./host.js";
+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 { current, type Current, type CurrentClient } from "./current.js";
 export { type Answerer, type Channel } from "./channel.js";
 export { type ProgramStartup } from "./startup.js";
 export { ClientServiceHandler, ServerServiceHandler, ServiceHandler, type ClientServiceChannel, type ServerServiceChannel, type ServiceChannel, type ServiceKey, type ServiceLifecycleEvents } from "@phreshos/core";
-export { Client, Endpoint, Process, Program, Server, type Window, type ProgramArea } 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, ProgramPermissions, 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 { Client, Endpoint, Process, Program, Server, type Window, type ProgramArea, 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";

package/dist/permissions.d.ts

@@ -1,3 +1,3 @@
-import type { ProgramPermissions } from "@phreshos/core";
+import type { ProgramPermission } from "@phreshos/core";
 /** Creates the persistent permission manager for one Program handle. */
-export default function permissions(program: unknown): ProgramPermissions;
+export default function permission(program: unknown): ProgramPermission;

package/dist/permissions.js

@@ -1,20 +1,20 @@
 import wire from "./wire.js";
 /** Creates the persistent permission manager for one Program handle. */
-export default function permissions(program) {
+export default function permission(program) {
     return {
         async get(name) {
-            const answer = await wire.request(["permissions", program, "get", name]);
+            const answer = await wire.request(["program-permission", program, "get", name]);
             return answer[0];
         },
         async getAll() {
-            const answer = await wire.request(["permissions", program, "getAll"]);
+            const answer = await wire.request(["program-permission", program, "getAll"]);
             return answer[0];
         },
         async set(name, value) {
-            await wire.request(["permissions", program, "set", name, value]);
+            await wire.request(["program-permission", program, "set", name, value]);
         },
         async delete(name) {
-            await wire.request(["permissions", program, "delete", name]);
+            await wire.request(["program-permission", program, "delete", name]);
         }
     };
 }

package/dist/service.d.ts

@@ -1,13 +1,13 @@
-import { type ClientServiceHandler, type ServerServiceDefinition, type ServerServiceHandler, type ServiceHandler, type ServiceKey } from "@phreshos/core";
+import { type ClientServiceHandler, type ServerServiceHandler, type ServiceHandler, type ServiceKey } from "@phreshos/core";
 import type { HandleAddress } from "./domain.js";
-export declare function service<EventsMap extends object = {}>(key: ServiceKey & {
+export declare function prepareService<EventsMap extends object = {}>(key: ServiceKey & {
     endpoint: "server";
 }): ServerServiceHandler<EventsMap>;
-export declare function service<EventsMap extends object = {}>(key: ServiceKey & {
+export declare function prepareService<EventsMap extends object = {}>(key: ServiceKey & {
     endpoint: "client";
 }): ClientServiceHandler<EventsMap>;
-export declare function service(key: ServiceKey): ServiceHandler;
-export declare function enableCurrentService(definition: ServerServiceDefinition): Promise<void>;
+export declare function prepareService(key: ServiceKey): ServiceHandler;
+export declare function enableCurrentService(name: string): Promise<void>;
 export declare function disableCurrentService(): Promise<void>;
 export declare function endpointService<EventsMap extends object = {}>(target: HandleAddress | null, endpoint: "server"): Promise<ServerServiceHandler<EventsMap> | null>;
 export declare function endpointService<EventsMap extends object = {}>(target: HandleAddress | null, endpoint: "client"): Promise<ClientServiceHandler<EventsMap> | null>;

package/dist/service.js

@@ -47,47 +47,43 @@ class ClientChannelHandle extends Events {
 }
 class ServerHandler extends ServerServiceBase {
     key;
-    program;
-    endpoint = "server";
     name;
     channel;
     constructor(key) {
         super();
         this.key = key;
-        this.program = key.program;
         this.name = key.name;
         this.channel = new ServerChannelHandle(key);
         bindEvents(this, new Events(...serviceEvents(key, "lifecycle")));
     }
-    async disabled() {
-        const answer = await wire.request(["service-disabled", this.key]);
+    async enabled() {
+        const answer = await wire.request(["service-enabled", this.key]);
         return answer[0];
     }
-    async docs() {
-        const answer = await wire.request(["service-docs", this.key]);
-        return answer[0];
+    async waitReady(timeout) {
+        await wire.request(["service-wait-ready", this.key, timeout], timeout);
     }
 }
 class ClientHandler extends ClientServiceBase {
     key;
-    program;
-    endpoint = "client";
     name;
     channel;
     constructor(key) {
         super();
         this.key = key;
-        this.program = key.program;
         this.name = key.name;
         this.channel = new ClientChannelHandle(key);
         bindEvents(this, new Events(...serviceEvents(key, "lifecycle")));
     }
-    async disabled() {
-        const answer = await wire.request(["service-disabled", this.key]);
+    async enabled() {
+        const answer = await wire.request(["service-enabled", this.key]);
         return answer[0];
     }
+    async waitReady(timeout) {
+        await wire.request(["service-wait-ready", this.key, timeout], timeout);
+    }
 }
-export function service(key) {
+export function prepareService(key) {
     if (!isServiceKey(key))
         throw new Error("A complete service key is required");
     const normalized = Object.freeze({ program: key.program, endpoint: key.endpoint, name: key.name });
@@ -98,15 +94,15 @@ export function service(key) {
             : new ClientHandler(normalized);
     });
 }
-export async function enableCurrentService(definition) {
-    await wire.request(["enable-service", definition]);
+export async function enableCurrentService(name) {
+    await wire.request(["enable-service", name]);
 }
 export async function disableCurrentService() {
     await wire.request(["disable-service"]);
 }
 export async function endpointService(target, endpoint) {
     const answer = await wire.request(["endpoint-service", target, endpoint]);
-    return answer[0] ? service(answer[0]) : null;
+    return answer[0] ? prepareService(answer[0]) : null;
 }
 function serviceEvents(key, scope) {
     return [

package/dist/theme.js

@@ -5,31 +5,17 @@ import wire from "./wire.js";
 export default class ServerTheme extends Events {
     constructor() {
         super((event, listener, impossible) => wire.on("host-theme", event, value => {
-            if (isObject(value))
-                listener(createThemeSnapshot(value));
+            listener(createThemeSnapshot(value));
         }, null, impossible), observer => wire.onAll("host-theme", (event, value) => {
-            if (typeof event === "string" && isObject(value))
+            if (typeof event === "string")
                 observer(event, createThemeSnapshot(value));
         }));
     }
     async snapshot() {
-        const answer = await wire.request(["theme"]);
-        if (!isObject(answer[0]))
-            throw new Error("The host returned an invalid Theme snapshot");
-        return createThemeSnapshot(answer[0]);
+        const [theme] = await wire.request(["theme"]);
+        return createThemeSnapshot(theme);
     }
     update = async (theme) => {
         await wire.request(["update-theme", theme]);
     };
 }
-function isObject(value) {
-    if (typeof value !== "object" || value === null || Array.isArray(value))
-        return false;
-    const theme = value;
-    const surface = theme.surface;
-    return typeof theme.background === "string" && typeof theme.foreground === "string" && typeof theme.accent === "string"
-        && typeof theme.spacing === "number" && typeof theme.radius === "number"
-        && typeof surface === "object" && surface !== null
-        && typeof surface.grain === "number" && typeof surface.animation === "number"
-        && typeof surface.backdrop === "number" && typeof surface.opacity === "number";
-}

package/dist/wire.js

@@ -69,7 +69,7 @@ class Wire {
     /** Resolves this endpoint's Process address only for operations that need it. */
     identity() {
         if (!this.identityPromise) {
-            const resolving = this.request(["process"]).then(value => {
+            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");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@phreshos/server",
-  "version": "0.1.10",
+  "version": "0.1.12",
   "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.8"
+    "@phreshos/core": "^0.1.11"
   },
   "dependencies": {
     "@msgpack/msgpack": "^3.1.3"
   },
   "devDependencies": {
-    "@phreshos/core": "^0.1.8",
+    "@phreshos/core": "^0.1.11",
     "@types/node": "^26.2.0",
     "typescript": "^6.0.3"
   }