@phreshos/core 0.1.0

package/README.md

@@ -0,0 +1,159 @@
+# `@phreshos/core`
+
+The Core SDK defines the domain objects and types shared by the client and
+server SDKs. It contains no transport or subscription implementation.
+
+## Package status
+
+This package is one component of a larger architecture that is still under
+active testing. The architecture's components will be released in stages as
+their contracts and integrations are verified.
+
+`@phreshos/core` is not intended to be used on its own. It defines the shared
+contracts consumed by the environment SDKs and does not provide a runtime
+implementation by itself.
+
+`Subscribable` is the independent receiving capability. It provides the
+contracts for `subscribe()`, `waitFor()`, `events()`, and `observe()`.
+`Publishable` independently provides `publish()`. `Askable` extends
+`Publishable` with `ask()`, because every target that can be asked can also be
+published to. A type may implement or compose only the capabilities it needs;
+being able to publish does not imply being able to subscribe.
+
+Finite asynchronous operations use a ten-second SDK deadline by default.
+`Askable.timeout()` creates an immutable deadline view for `ask()` only;
+`waitFor()` and `waitReady()` accept a deadline directly. `events()` is a
+long-lived iterator with a bounded queue rather than a timed request. An ask's
+single deadline covers both waiting for its current Server incarnation to
+become ready and waiting for the eventual answer.
+
+Every persistent registration returns its only cleanup function:
+
+```ts
+const stop = target.subscribe("event", handler)
+stop()
+```
+
+There are no separate `unsubscribe()` or `unobserve()` methods and no
+one-time subscription operation. Observation APIs such as `observeAsks()` and
+`observeAnswers()` follow the same returned-cleanup rule.
+
+```ts
+import type { Subscribable } from "@phreshos/core"
+
+type Events = {
+  exit: {
+    status: string
+    code: number
+  }
+}
+
+declare const target: Subscribable<Events>
+
+target.subscribe("exit", message => {
+  message.status
+  message.code
+})
+```
+
+Known messages are inferred from the target. An explicit generic or callback
+annotation may narrow that message, but an incompatible replacement is a type
+error. `observe()` receives a `Capture` containing only the facts guaranteed by
+every Subscribable: `event` and `message`. It makes no assumption about a
+sender or destination.
+
+An unparameterized Channel or traffic surface accepts application-defined event
+names with an `unknown` payload. Supplying an event map narrows both the names
+and their payloads; names outside that map are then rejected.
+
+`events()` applies the same message inference and narrowing rules and exposes a
+named event as an `AsyncIterableIterator`.
+
+`Endpoint` is the shared base of Server and Client and composes only
+`Publishable`. It is an address and lifecycle-control handle, never a receiving
+surface. Server additionally composes `Askable`. Every event explicitly
+addressed to the executing Endpoint enters only through its contextual
+`Channel`, whose `ChannelMessage` contains the otherwise unknown sender. An
+environment may narrow that reference to `Endpoint | null` when its isolation
+boundary deliberately hides foreign identities.
+
+Broad inspection is deliberately separated as `endpoint.traffic`. The Endpoint
+handle already identifies the source, so ordinary traffic messages contain only
+the unknown destination and payload. Every traffic surface exposes
+`observeAsks()` because either Endpoint kind may originate a question. A
+Server's traffic additionally exposes `observeAnswers()`, because only a Server
+can originate an answer. These captures include their event, correlation ID,
+destination, and question payload or answer `Outcome`.
+
+Every Endpoint exposes `exists()`, `start()`, and `stop()`. Endpoint lifecycle
+is observed through the owning Process's `serverStart`, `serverStop`,
+`clientStart`, and `clientStop` events rather than through Endpoint
+subscriptions.
+
+`Server` and `Client` are public, logic-free Endpoint specializations. Server
+adds one-payload `ask()` and answer traffic observation. Client returns its owned
+Window. Window returns its owning Client, preserving navigation in both
+directions without introducing host or transport knowledge.
+
+Program and Process complete the ownership hierarchy. Every public domain
+object remains a real runtime class for identity and `instanceof`, while the
+capabilities it implements are independent interfaces. Constructors are public
+and logic-free during this contract phase; all methods remain declarations
+until an environment SDK supplies their implementation.
+Core also owns the common launch, geometry, lifecycle-message, ChannelMessage,
+ChannelCapture, TrafficMessage, and TrafficCapture types used by both
+environments.
+
+Process parentage belongs to `Process`, not to contextual SDK state.
+Each live Process retains only a handle to its immediate parent.
+`process.parent()` returns `null` when no accessible parent handle exists. It
+does not preserve historical lineage: calling it through an exited Process
+handle, or after the retained parent has disappeared, rejects because the
+represented Process does not exist. A future `current.parent()` may flatten
+this operation, but does not own the relationship.
+
+Client traversal is structurally confined to its current Program. A
+cross-Program parent handle is never supplied to the client, so traversal stops
+at `null`. A fabricated or otherwise unauthorized Process handle is
+indistinguishable from a nonexistent Process and every operation through it
+rejects accordingly.
+
+## Program configuration
+
+Core is also the single source of truth for the authoring contract consumed by
+the CLI. `defineConfig()` provides contextual typing for `phresh.config.ts` and
+returns the description unchanged:
+
+```ts
+import { defineConfig } from "@phreshos/core"
+
+export default defineConfig({
+  identity: "my-program",
+  server: {
+    location: "./dist/server",
+    startCommand: "node main.js",
+    development: {
+      startCommand: "node --watch --import tsx source/server/main.ts"
+    }
+  },
+  client: {
+    location: "./dist/client",
+    development: {
+      url: "http://localhost:5173/",
+      startCommand: "npm run dev"
+    }
+  }
+})
+```
+
+The declaration must contain a Server, a Client, or both. Development settings
+remain authoring metadata; the CLI derives the appropriate runtime description
+for each mode.
+
+## Program-owned resources
+
+Every Program exposes the same storage contracts in both environments:
+filesystem-like `data` and `cache`, a key-value `store`, read-only SQL `logs`,
+and a writable SQLite `database`. The Server SDK refines its filesystem areas
+with `path()` and safe `resolve()` access; these host filesystem paths are
+structurally absent from the Client SDK.

package/dist/askable.d.ts

@@ -0,0 +1,22 @@
+import type { Publishable } from "./publishable.js";
+/** An immutable Askable view using one caller-selected deadline. */
+export interface TimedAskable {
+    /** Sends one question and waits within the selected deadline. */
+    ask<Answer = unknown, Payload = unknown>(event: string, payload: Payload): Promise<Answer>;
+}
+/** A publishing target that can also receive a question and return an answer. */
+export interface Askable<Events extends object = {}, Fallback = unknown> extends Publishable<Events, Fallback> {
+    /**
+     * Sends one question payload to this target and waits for its answer.
+     *
+     * The SDK uses a ten-second deadline by default. It sends the question only
+     * after the current Server incarnation becomes ready. The operation rejects
+     * immediately when that Server is absent, and also rejects if the incarnation
+     * stops before readiness or before answering. One SDK deadline covers both
+     * readiness and the answer. The boundary cannot infer whether an answerer
+     * exists, so a ready unanswered question waits for that deadline.
+     */
+    ask<Answer = unknown, Payload = unknown>(event: string, payload: Payload): Promise<Answer>;
+    /** Returns an immutable view whose `ask()` uses this deadline in milliseconds. */
+    timeout(milliseconds: number): TimedAskable;
+}

package/dist/channel.d.ts

@@ -0,0 +1,20 @@
+import type { Endpoint } from "./endpoint.js";
+import type { Captures, Subscribable } from "./subscribable.js";
+/** One application value arriving through the current Endpoint's Channel. */
+export type ChannelMessage<Payload = unknown, From = Endpoint> = Readonly<{
+    /** Endpoint that sent the message, or `null` when its identity is outside this boundary. */
+    from: From;
+    /** Single value supplied by the publisher. */
+    payload: Payload;
+}>;
+/** Applies the sender envelope to every application event accepted here. */
+export type ChannelEvents<Events extends object, From = Endpoint> = {
+    readonly [Event in keyof Events]: ChannelMessage<Events[Event], From>;
+};
+type ChannelFallback<Events extends object, From> = keyof Events extends never ? ChannelMessage<unknown, From> : never;
+/** Every application event observable through a Channel. */
+export type ChannelCapture<Events extends object = {}, From = Endpoint> = Captures<ChannelEvents<Events, From>, ChannelFallback<Events, From>>;
+/** Events explicitly accepted by the current Endpoint. */
+export interface Channel<Events extends object = {}, From = Endpoint> extends Subscribable<ChannelEvents<Events, From>, ChannelFallback<Events, From>> {
+}
+export {};

package/dist/client.d.ts

@@ -0,0 +1,19 @@
+import { Endpoint, type EndpointTraffic } from "./endpoint.js";
+import type { LaunchClient } from "./launch.js";
+import type { Server } from "./server.js";
+import type { Window } from "./window.js";
+/** Broad communication originating from one Client. */
+export interface ClientTraffic<Events extends object = {}, To = Endpoint, AskTo = Server> extends EndpointTraffic<Events, To, AskTo> {
+}
+/** The client Endpoint of a Process. */
+export declare class Client<Events extends object = {}> extends Endpoint<Events> {
+    constructor();
+}
+export interface Client<Events extends object = {}> {
+    /** Broad communication originating from this Client. */
+    readonly traffic: ClientTraffic<Events>;
+    /** Starts a fresh Client and Window using optional Process-local overrides. */
+    start(overrides?: LaunchClient): Promise<void>;
+    /** Returns the Window owned by this live Client. */
+    window(): Promise<Window>;
+}

package/dist/client.js

@@ -0,0 +1,7 @@
+import { Endpoint } from "./endpoint.js";
+/** The client Endpoint of a Process. */
+export class Client extends Endpoint {
+    constructor() {
+        super();
+    }
+}

package/dist/config.d.ts

@@ -0,0 +1,81 @@
+import type { Layer, Position, Size } from "./launch.js";
+/** Development settings for a Program's Server. */
+export type ServerDevelopment = Readonly<{
+    /** Command that starts the development Server from the project directory. */
+    startCommand: string;
+}>;
+/** Development settings for a Program's Client. */
+export type ClientDevelopment = Readonly<{
+    /** HTTP(S) URL served by the Client's development server. */
+    url: string;
+    /** Optional command that starts the Client's development server. */
+    startCommand?: string;
+}>;
+/** Authoring declaration for a Program's Server. */
+export type ServerConfig = Readonly<{
+    /** Production directory containing the Server. */
+    location: string;
+    /** Whether a default Process starts its Server. Defaults to `true`. */
+    start?: boolean;
+    /** Optional preparation command run from {@link location} while installing. */
+    installCommand?: string;
+    /** Command that starts the production Server from {@link location}. */
+    startCommand: string;
+    /** Settings used only by the development command. */
+    development?: ServerDevelopment;
+}>;
+/** Authoring declaration for a Program's Client and initial Window. */
+export type ClientConfig = Readonly<{
+    /** Production directory containing the Client and its `index.html`. */
+    location: string;
+    /** Whether a default Process starts its Client. Defaults to `true`. */
+    start?: boolean;
+    /** Initial Window title. Defaults to the Program name. */
+    title?: string;
+    /** Initial Window size. */
+    size?: Size;
+    /** Initial Window position. */
+    position?: Position;
+    /** Structurally isolated desktop layer containing the Window. */
+    layer?: Layer;
+    /** Whether the Window initially opens minimized. */
+    minimize?: boolean;
+    /** Settings used only by the development command. */
+    development?: ClientDevelopment;
+}>;
+type Description = Readonly<{
+    /** Stable public identity written in kebab-case. */
+    identity: string;
+    /** Human-readable Program name. Defaults to {@link identity}. */
+    name?: string;
+    /** Program version shown to people and included in packages. */
+    version?: string;
+    /** Short human-readable explanation of what the Program does. */
+    description?: string;
+    /** Markdown file that officially introduces the Program's API. */
+    apiDocs?: string;
+    /** Directory containing the Program's sized icons. */
+    icons?: string;
+    /** Command run before production start, installation, and packaging. */
+    buildCommand?: string;
+}>;
+/**
+ * The authoring description read from `phresh.config.ts`.
+ *
+ * A Program must declare a Server, a Client, or both.
+ */
+export type Config = Description & (Readonly<{
+    server: ServerConfig;
+    client?: ClientConfig;
+}> | Readonly<{
+    server?: ServerConfig;
+    client: ClientConfig;
+}>);
+/**
+ * Defines a Program authoring description with contextual typing.
+ *
+ * This helper performs no work and returns the supplied description unchanged.
+ * The CLI validates and derives it for development, production, or packaging.
+ */
+export declare function defineConfig<const Description extends Config>(config: Description): Description;
+export {};

package/dist/config.js

@@ -0,0 +1,9 @@
+/**
+ * Defines a Program authoring description with contextual typing.
+ *
+ * This helper performs no work and returns the supplied description unchanged.
+ * The CLI validates and derives it for development, production, or packaging.
+ */
+export function defineConfig(config) {
+    return config;
+}

package/dist/endpoint.d.ts

@@ -0,0 +1,70 @@
+import type { Process } from "./process.js";
+import type { Publishable } from "./publishable.js";
+import type { Server } from "./server.js";
+import type { Captures, Cleanup, Subscribable } from "./subscribable.js";
+/** One application value observed in traffic originating from an Endpoint. */
+export type TrafficMessage<Payload = unknown, To = Endpoint> = Readonly<{
+    /** Destination Endpoint, or `null` when its identity is outside this boundary. */
+    to: To;
+    /** Single value supplied by the publisher. */
+    payload: Payload;
+}>;
+/** Applies destination metadata to every observed ordinary event. */
+export type TrafficEvents<Events extends object, To = Endpoint> = {
+    readonly [Event in keyof Events]: TrafficMessage<Events[Event], To>;
+};
+type TrafficFallback<Events extends object, To> = keyof Events extends never ? TrafficMessage<unknown, To> : never;
+/** One question sent by this Endpoint to a Server. */
+export type AskMessage<Payload = unknown, To = Server> = Readonly<{
+    /** Destination Server, or `null` when its identity is outside this boundary. */
+    to: To;
+    /** Single question value supplied by the asker. */
+    payload: Payload;
+}>;
+/** One observed question sent by this Endpoint. */
+export type AskCapture<Payload = unknown, To = Server> = Readonly<{
+    /** Event addressed by the question. */
+    event: string;
+    /** Correlation identity shared with the eventual answer. */
+    questionId: string;
+    /** Question destination and payload. */
+    message: AskMessage<Payload, To>;
+}>;
+/** A callback that observes questions sent by this Endpoint. */
+export type AskObserver<Payload = unknown, To = Server> = (capture: AskCapture<Payload, To>) => unknown;
+/** Every ordinary publication observable in traffic from one Endpoint. */
+export type TrafficCapture<Events extends object = {}, To = Endpoint> = Captures<TrafficEvents<Events, To>, TrafficFallback<Events, To>>;
+/** Broad communication originating from one Endpoint, regardless of destination. */
+export interface EndpointTraffic<Events extends object = {}, To = Endpoint, AskTo = Server> extends Subscribable<TrafficEvents<Events, To>, TrafficFallback<Events, To>> {
+    /** Observes questions originating from this Endpoint. */
+    observeAsks<Payload = unknown>(observer: AskObserver<Payload, AskTo>): Cleanup;
+}
+/** The shared Process endpoint represented by Server and Client. */
+export declare class Endpoint<Events extends object = {}> {
+    constructor();
+}
+export interface Endpoint<Events extends object = {}> extends Publishable {
+    /** Broad communication originating from this Endpoint. */
+    readonly traffic: EndpointTraffic<Events>;
+    /** Returns the Process that owns this Endpoint. */
+    process(): Process;
+    /** Returns whether this Endpoint currently has a live incarnation. */
+    exists(): Promise<boolean>;
+    /**
+     * Starts a fresh incarnation without waiting for Server readiness.
+     *
+     * Rejects when the Process is gone or inaccessible, the Program did not
+     * declare this endpoint kind, the Endpoint is already starting or live, or
+     * creation fails.
+     */
+    start(): Promise<void>;
+    /**
+     * Stops the current incarnation and destroys its boundary-owned resources.
+     *
+     * Rejects when the Process is gone or inaccessible, the Endpoint is already
+     * stopping or absent, this is the Process's final live Endpoint, or stopping
+     * fails. Stopping never exits the Process implicitly.
+     */
+    stop(): Promise<void>;
+}
+export {};

package/dist/endpoint.js

@@ -0,0 +1,4 @@
+/** The shared Process endpoint represented by Server and Client. */
+export class Endpoint {
+    constructor() { }
+}

package/dist/launch.d.ts

@@ -0,0 +1,35 @@
+/** A pixel count or a relative linear expression. */
+export type Value = number | string;
+/** A Window's top-left position. */
+export type Position = Readonly<{
+    /** Horizontal position. */
+    x: Value;
+    /** Vertical position. */
+    y: Value;
+}>;
+/** A Window's width and height. */
+export type Size = Readonly<{
+    /** Window width. */
+    width: Value;
+    /** Window height. */
+    height: Value;
+}>;
+/** A structurally isolated desktop layer. */
+export type Layer = "window" | "under" | "over";
+/** Every structurally isolated desktop layer. */
+export declare const layers: readonly Layer[];
+/** Per-Process overrides used when starting a Client and its Window. */
+export type LaunchClient = Readonly<{
+    size?: Size;
+    position?: Position;
+    layer?: Layer;
+    location?: string;
+    minimize?: boolean;
+}>;
+/** Initial endpoint selection and immutable options for one Process. */
+export type Launch = Readonly<{
+    name?: string;
+    server?: boolean;
+    client?: boolean | LaunchClient;
+    options?: Readonly<Record<string, string>>;
+}>;

package/dist/launch.js

@@ -0,0 +1,2 @@
+/** Every structurally isolated desktop layer. */
+export const layers = ["window", "under", "over"];

package/dist/main.d.ts

@@ -0,0 +1,16 @@
+export { type Message, type Cleanup, type Capture, type Captures, type EventMessage, type EventName, type EventObserver, type EventOptions, type EventSubscriber, type Subscribable } from "./subscribable.js";
+export { type Publishable } from "./publishable.js";
+export { type Askable, type TimedAskable } from "./askable.js";
+export { type Outcome } from "./outcome.js";
+export { type ServedFile } from "./served-file.js";
+export { type DirectoryStat, type EntryStat, type FileStat, type OtherStat, type ProgramArea, type ProgramStore } from "./storage.js";
+export { type LogKind, type LogRecord, type LogSource, type ProgramSql } from "./sql.js";
+export { Endpoint, type AskCapture, type AskMessage, type AskObserver, type EndpointTraffic, type TrafficCapture, type TrafficEvents, type TrafficMessage } from "./endpoint.js";
+export { type Channel, type ChannelCapture, type ChannelEvents, type ChannelMessage } from "./channel.js";
+export { Server, type AnswerCapture, type AnswerMessage, type AnswerObserver, type ServerTraffic } from "./server.js";
+export { Client, type ClientTraffic } from "./client.js";
+export { Process, type Exit, type ProcessEvents } from "./process.js";
+export { Program, type ClientDeclaration, type EndpointDeclaration, type ProgramEvents, type ProgramProcessExit, type ProgramServerStop } from "./program.js";
+export { Window, type WindowEvents, type WindowState } from "./window.js";
+export { layers, type Launch, type LaunchClient, type Layer, type Position, type Size, type Value } from "./launch.js";
+export { defineConfig, type ClientConfig, type ClientDevelopment, type Config, type ServerConfig, type ServerDevelopment } from "./config.js";

package/dist/main.js

@@ -0,0 +1,16 @@
+export {} from "./subscribable.js";
+export {} from "./publishable.js";
+export {} from "./askable.js";
+export {} from "./outcome.js";
+export {} from "./served-file.js";
+export {} from "./storage.js";
+export {} from "./sql.js";
+export { Endpoint } from "./endpoint.js";
+export {} from "./channel.js";
+export { Server } from "./server.js";
+export { Client } from "./client.js";
+export { Process } from "./process.js";
+export { Program } from "./program.js";
+export { Window } from "./window.js";
+export { layers } from "./launch.js";
+export { defineConfig } from "./config.js";

package/dist/outcome.d.ts

@@ -0,0 +1,8 @@
+/** The transport-neutral result of an operation that may fail. */
+export type Outcome<Result = unknown> = Readonly<{
+    success: true;
+    result: Result;
+}> | Readonly<{
+    success: false;
+    error: string;
+}>;

package/dist/process.d.ts

@@ -0,0 +1,58 @@
+import type { Client } from "./client.js";
+import type { Program } from "./program.js";
+import type { Server } from "./server.js";
+import type { Subscribable } from "./subscribable.js";
+/** How an operating-system-backed endpoint or Process finished. */
+export type Exit = Readonly<{
+    /** Whether the endpoint exited normally or was terminated by a signal. */
+    status: "exited" | "signaled";
+    /** Numeric exit code, or `null` when no code was reported. */
+    code: number | null;
+    /** Signal name, or `null` when no signal ended it. */
+    signal: string | null;
+}>;
+/** Lifecycle events emitted by one Process. */
+export type ProcessEvents = {
+    /** The Server entered a new live incarnation. */
+    serverStart: undefined;
+    /** The Server incarnation ended. */
+    serverStop: Omit<Exit, "status">;
+    /** The authoritative Client state was created. */
+    clientStart: undefined;
+    /** The authoritative Client state ended. */
+    clientStop: undefined;
+    /** The complete Process ended. */
+    exit: Exit;
+};
+/** One live execution of a Program. */
+export declare class Process<Events extends object = {}> {
+    constructor();
+}
+export interface Process<Events extends object = {}> extends Subscribable<ProcessEvents & Events, never> {
+    /** Immutable runtime identity. */
+    readonly identity: string;
+    /** Optional meaningful name unique among this Program's live Processes. */
+    readonly name: string | null;
+    /** Instant at which this Process was created. */
+    readonly startedAt: Date;
+    /** Permanent handle to this Process's Server. */
+    readonly server: Server;
+    /** Permanent handle to this Process's Client. */
+    readonly client: Client;
+    /** Returns the Program that owns this Process. */
+    program(): Program;
+    /**
+     * Returns the Process whose `createProcess()` call created this Process.
+     *
+     * Returns `null` when this Process has no accessible parent handle. Rejects
+     * when this Process or its retained parent no longer exists. Client
+     * environments never expose a parent belonging to another Program.
+     */
+    parent(): Promise<Process | null>;
+    /** Returns one immutable launch option. */
+    option(name: string): Promise<string | undefined>;
+    /** Ends the complete Process and all live Endpoints. */
+    exit(): Promise<void>;
+    /** Returns whether this Process has ended. */
+    exited(): Promise<boolean>;
+}

package/dist/process.js

@@ -0,0 +1,4 @@
+/** One live execution of a Program. */
+export class Process {
+    constructor() { }
+}

package/dist/program.d.ts

@@ -0,0 +1,96 @@
+import type { Launch, Layer, Position, Size } from "./launch.js";
+import type { Exit, Process } from "./process.js";
+import type { ProgramSql } from "./sql.js";
+import type { ProgramArea, ProgramStore } from "./storage.js";
+import type { Subscribable } from "./subscribable.js";
+/** Resolved declaration shared by Server and Client endpoint kinds. */
+export type EndpointDeclaration = Readonly<{
+    /** Whether a default Process starts this declared Endpoint. */
+    start: boolean;
+}>;
+/** Resolved Client declaration and its default Window state. */
+export type ClientDeclaration = EndpointDeclaration & Readonly<{
+    /** Default Window title, or `null` when the system supplies it. */
+    title: string | null;
+    /** Default Window size, or `null` when the system supplies it. */
+    size: Size | null;
+    /** Default Window position, or `null` when the system supplies it. */
+    position: Position | null;
+    /** Default Window layer, or `null` for the system default. */
+    layer: Layer | null;
+    /** Default minimized state, or `null` for the system default. */
+    minimize: boolean | null;
+}>;
+export type ProgramProcessExit = Exit & Readonly<{
+    /** Process that ended. */
+    process: Process;
+}>;
+export type ProgramServerStop = Omit<Exit, "status"> & Readonly<{
+    /** Process whose Server incarnation ended. */
+    process: Process;
+}>;
+/** Lifecycle events scoped to one Program. */
+export type ProgramEvents = {
+    /** One Process's Server entered a new live incarnation. */
+    serverStart: Process;
+    /** One Process's Server incarnation ended. */
+    serverStop: ProgramServerStop;
+    /** One Process's Client state was created. */
+    clientStart: Process;
+    /** One Process's Client state ended. */
+    clientStop: Process;
+    /** A Process entered this Program's runtime set. */
+    processCreate: Process;
+    /** A Process left this Program's runtime set. */
+    processExit: ProgramProcessExit;
+    /** This Program left the runtime registry. */
+    forget: undefined;
+    /** This Program left the installed state. */
+    uninstall: Readonly<{
+        everythingRemoved: boolean;
+    }>;
+};
+/** The stable domain root from which Processes are created. */
+export declare class Program<Events extends object = {}> {
+    constructor();
+}
+export interface Program<Events extends object = {}> extends Subscribable<ProgramEvents & Events, never> {
+    /** Stable public identity. */
+    readonly identity: string;
+    /** Human-readable name. */
+    readonly name: string;
+    /** Declared version, or `null`. */
+    readonly version: string | null;
+    /** Declared description, or `null`. */
+    readonly description: string | null;
+    /** Server declaration, or `null` when this Program cannot start one. */
+    readonly server: EndpointDeclaration | null;
+    /** Client declaration, or `null` when this Program cannot start one. */
+    readonly client: ClientDeclaration | null;
+    /** Persistent filesystem data shared by every Process of this Program. */
+    readonly data: ProgramArea;
+    /** Disposable filesystem data shared by every Process of this Program. */
+    readonly cache: ProgramArea;
+    /** Persistent key-value storage shared by every Process of this Program. */
+    readonly store: ProgramStore;
+    /** Read-only SQL access to captured Client and Server output. */
+    readonly logs: ProgramSql;
+    /** Writable SQLite database owned by this Program. */
+    readonly database: ProgramSql;
+    /** Returns every live Process of this Program available to this SDK. */
+    processes(): Promise<Process[]>;
+    /** Finds a live Process by identity or Program-local name. */
+    getProcess(identityOrName: string): Promise<Process | null>;
+    /** Creates one Process of this Program. */
+    createProcess(launch?: Launch): Promise<Process>;
+    /** Returns the official Markdown API entry point, or `null`. */
+    apiDocs(): Promise<string | null>;
+    /** Returns whether this Program currently has an installed form. */
+    installed(): Promise<boolean>;
+    /** Removes this Program's installed form. */
+    uninstall(everything?: boolean): Promise<void>;
+    /** Ends all Processes and removes this Program from the runtime registry. */
+    forget(): Promise<void>;
+    /** Ends every live Process and returns their identities. */
+    exitAll(): Promise<string[]>;
+}

package/dist/program.js

@@ -0,0 +1,4 @@
+/** The stable domain root from which Processes are created. */
+export class Program {
+    constructor() { }
+}