babavoss 0.0.1 → 0.12.0

package/src/server/edge.ts

@@ -0,0 +1,332 @@
+// The GUI server's routes, answered from what the kernel sent and by asking
+// the kernel; and the windows' sockets, each following one baba: a frame
+// per round pushed by the kernel and cut to what the window asks for, and
+// the window's fires, reads and raw writes forwarded and answered on the
+// same socket, in order. No file, no project, no Node here: only memory and IPC.
+import { isIP } from "node:net";
+import type { Server, ServerWebSocket, WebSocketHandler } from "bun";
+import type { Serve, Described, Failure, Describe, DescribeAnswer, View, ViewAnswer, Call, CallAnswer, Refresh, RefreshAnswer, Restart, RestartAnswer, Browse, BrowseAnswer, Add, AddAnswer } from "./messages.ts";
+import type { Raw } from "../ecs/runtime.ts";
+import type { Json } from "../kernel/schema.ts";
+import { frameHeader, resolveInterest, sliceFrame, type Resolved } from "../ecs/codec.ts";
+import { CLOSE, SOCKET_PROTOCOL, type Down, type Interest, type Up } from "./protocol.ts";
+
+interface Pairs { describe: [Describe, DescribeAnswer]; view: [View, ViewAnswer]; call: [Call, CallAnswer]; refresh: [Refresh, RefreshAnswer]; restart: [Restart, RestartAnswer]; browse: [Browse, BrowseAnswer]; add: [Add, AddAnswer] }
+type Unnumbered<T> = T extends unknown ? Omit<T, "id"> : never;
+/** Sends a request to the kernel, numbered by the sender, and resolves with its answer. */
+export type Ask = <K extends keyof Pairs>(m: Unnumbered<Pairs[K][0]>) => Promise<Pairs[K][1]>;
+
+/** Hosts no DNS answer can rebind to: IP addresses and localhost names. */
+export function localHost(host: string): boolean {
+  const name = host.startsWith("[") ? host.slice(1, host.indexOf("]")) : host.replace(/:\d+$/, "");
+  const lower = name.toLowerCase();
+  return isIP(name) !== 0 || lower === "localhost" || lower.endsWith(".localhost");
+}
+
+function same(a: string, b: string): boolean {
+  if (a.length !== b.length) return false;
+  let d = 0;
+  for (let i = 0; i < a.length; i++) d |= a.charCodeAt(i) ^ b.charCodeAt(i);
+  return d === 0;
+}
+
+function tokenOf(req: globalThis.Request): string | null {
+  const auth = req.headers.get("authorization");
+  if (auth?.startsWith("Bearer ")) return auth.slice(7).trim();
+  return req.headers.get("x-voss-token");
+}
+
+const json = (v: unknown, status = 200) => Response.json(v, { status, headers: { "cache-control": "no-store" } });
+const text = (s: string, status: number) => new Response(s, { status, headers: { "cache-control": "no-store" } });
+const html = (s: string) => new Response(s, { headers: { "content-type": "text/html; charset=utf-8", "cache-control": "no-store" } });
+
+function status(code: string): number {
+  return code === "nokey" || code === "noaction" || code === "noquery" || code === "noview" || code === "entity" || code === "name" ? 404 : code === "args" || code === "owner" ? 400 : 500;
+}
+const failed = (f: Failure) => json({ error: { code: f.code, message: f.message } }, status(f.code));
+
+const RAW = new Set(["spawn", "add", "remove", "despawn", "set"]);
+
+// ---- the sockets ------------------------------------------------------------
+
+/** A window's socket: which baba it follows, where it stands, and what it asks for. */
+export interface Peer {
+  name: string;
+  authed: boolean;
+  /** The round the window holds: what the next frame is since. */
+  since: number;
+  /** A whole or a grown interest's parts are on their way: frames pushed meanwhile wait behind them. */
+  ready: boolean;
+  buffer: { round: number; frame: Uint8Array }[];
+  /** Everything that re-bases the stream, in turn: a hello, a resync, a grown interest. */
+  queue: Promise<void>;
+  /** The frame's layout, from the manifest at hello: what interest names resolve against. */
+  cid: Map<string, number>;
+  rid: Map<string, number>;
+  /** What the window asks for, by name and resolved: every frame is cut to it. */
+  interest: Interest;
+  want: Resolved;
+}
+
+/** Bytes a window may have unread before it is dropped to resync, as a source stream that overflows is. */
+const BEHIND = 8 * 1024 * 1024;
+
+export interface Edge {
+  fetch(req: globalThis.Request, server: Server<Peer>): Promise<Response | undefined>;
+  websocket: WebSocketHandler<Peer>;
+  /** A round of `name`: its frame to every window following it. */
+  push(name: string, round: number, frame: Uint8Array): void;
+  /** `name`'s generation advanced: its windows are told, and hello again. */
+  generation(name: string, gen: number): void;
+}
+
+/** The names an interest newly asks the values or presence of, over the one before; null when none. */
+export function added(before: Interest, after: Interest): Interest | null {
+  if (after.all) return before.all ? null : { all: true };
+  const had = (xs?: string[]) => new Set(xs ?? []);
+  const bp = had(before.presence), bv = had(before.values), br = had(before.resources);
+  const values = (after.values ?? []).filter((n) => !bv.has(n));
+  const presence = (after.presence ?? []).filter((n) => !bp.has(n) && !bv.has(n) && !values.includes(n));
+  const resources = (after.resources ?? []).filter((n) => !br.has(n));
+  const parts: Record<string, number[]> = {};
+  for (const [name, es] of Object.entries(after.parts ?? {})) {
+    if (bv.has(name) || values.includes(name)) continue;
+    const was = new Set(before.parts?.[name] ?? []);
+    const fresh = es.filter((e) => !was.has(e));
+    if (fresh.length) parts[name] = fresh;
+  }
+  if (!values.length && !presence.length && !resources.length && !Object.keys(parts).length) return null;
+  return { presence, values, parts, resources };
+}
+
+export function edge(state: Serve, ask: Ask): Edge {
+  // The kernel replaces the projects on a refresh; the names follow.
+  const names = { has: (n: string) => state.projects.some((p) => p.name === n) };
+  const peers = new Map<string, Set<ServerWebSocket<Peer>>>();
+  const join = (ws: ServerWebSocket<Peer>) => { let s = peers.get(ws.data.name); if (!s) { s = new Set(); peers.set(ws.data.name, s); } s.add(ws); };
+  const leave = (ws: ServerWebSocket<Peer>) => { peers.get(ws.data.name)?.delete(ws); };
+  const tell = (ws: ServerWebSocket<Peer>, m: Down) => { ws.send(JSON.stringify(m)); };
+  const open = (ws: ServerWebSocket<Peer>) => ws.readyState === 1;
+
+  /** The frame cut to the window's interest and sent, if anything is left of it; where the window stands moves with what it was sent. A whole always goes: it is the window's state from here. */
+  const give = (ws: ServerWebSocket<Peer>, frame: Uint8Array, whole = false) => {
+    const d = ws.data;
+    const { round } = frameHeader(frame);
+    const out = d.want.all ? frame : sliceFrame(frame, d.want, d.since) ?? (whole ? frame : null);
+    if (!out) return;
+    ws.send(out);
+    d.since = round;
+  };
+
+  /** A frame from the kernel: the state since where the window stands, or the parts it began to ask for. */
+  const fetchFrame = async (ws: ServerWebSocket<Peer>, m: { since: number; parts?: Interest }): Promise<Uint8Array | null> => {
+    const a = await ask<"call">({ type: "call", name: ws.data.name, kind: "state", since: m.since, frame: true, wait: false, ...(m.parts ? { parts: m.parts } : {}) });
+    if (!a.ok) { ws.close(CLOSE.down, a.message); return null; }
+    return open(ws) ? a.value as Uint8Array : null;
+  };
+
+  /**
+   * Re-bases the stream: frames pushed while `fn` fetches wait, then go in
+   * order with what it fetched, nothing lost between; one at a time per
+   * window, so a hello, a resync and a grown interest never cross.
+   */
+  const rebase = (ws: ServerWebSocket<Peer>, fn: () => Promise<void>) => {
+    const d = ws.data;
+    d.queue = d.queue.then(async () => {
+      d.ready = false; d.buffer = [];
+      try { await fn(); } finally {
+        d.ready = true;
+        for (const b of d.buffer) if (b.round > d.since) give(ws, b.frame);
+        d.buffer = [];
+      }
+    }).catch(() => {});
+  };
+
+  /** The window's state from where it stands: a welcome first when it just said hello. */
+  const sync = (ws: ServerWebSocket<Peer>, welcome: boolean) => rebase(ws, async () => {
+    const d = ws.data;
+    join(ws);
+    if (welcome) {
+      const a = await ask<"describe">({ type: "describe", name: d.name, since: 0 });
+      if (!a.ok) { ws.close(CLOSE.unknown, a.message); return; }
+      const m = a.value.manifest;
+      if (!m) { ws.close(CLOSE.down, `${d.name} is not running`); return; }
+      const declared = (x: Record<string, { schema: Json }>) => Object.entries(x).map(([name, v]) => ({ name, json: v.schema }));
+      d.cid = new Map(Object.keys(m.components).map((n, i) => [n, i])); d.rid = new Map(Object.keys(m.resources).map((n, i) => [n, i]));
+      d.want = resolveInterest(d.interest, d.cid, d.rid);
+      tell(ws, { type: "welcome", protocol: SOCKET_PROTOCOL, gen: a.value.gen, components: declared(m.components), resources: declared(m.resources) });
+    }
+    const frame = await fetchFrame(ws, { since: d.since });
+    if (frame) give(ws, frame, frameHeader(frame).whole);
+  });
+
+  /** The window began to ask for more: those parts as they are, in order with the rounds. */
+  const grow = (ws: ServerWebSocket<Peer>, more: Interest) => {
+    if (more.all) { ws.data.since = 0; sync(ws, false); return; }
+    rebase(ws, async () => {
+      const d = ws.data;
+      const frame = await fetchFrame(ws, { since: 0, parts: more });
+      if (!frame) return;
+      const { round } = frameHeader(frame);
+      for (const b of d.buffer) if (b.round <= round) give(ws, b.frame);
+      d.buffer = d.buffer.filter((b) => b.round > round);
+      give(ws, frame);
+    });
+  };
+
+  async function call(ws: ServerWebSocket<Peer>, m: Extract<Up, { id: number }>): Promise<void> {
+    const d = ws.data;
+    let c: Unnumbered<Call>;
+    if (m.type === "fire") c = { type: "call", name: d.name, kind: "fire", target: m.name, args: m.args ?? {}, ...(m.key ? { key: m.key } : {}) };
+    else if (m.type === "read") c = { type: "call", name: d.name, kind: "read", target: m.name, args: m.args ?? {} };
+    else {
+      const { type: _t, id: _i, op, ...rest } = m;
+      if (!RAW.has(op)) { tell(ws, { type: "result", id: m.id, ok: false, code: "notfound", message: `no raw op ${op}` }); return; }
+      c = { type: "call", name: d.name, kind: "raw", raw: { op, ...rest } as Raw };
+    }
+    const a = await ask<"call">(c);
+    if (!open(ws)) return;
+    if (a.ok) tell(ws, { type: "result", id: m.id, ok: true, value: a.value, ...(a.round !== undefined ? { round: a.round } : {}) });
+    else tell(ws, { type: "result", id: m.id, ok: false, code: a.code, message: a.message });
+  }
+
+  const websocket: WebSocketHandler<Peer> = {
+    async message(ws, raw) {
+      if (typeof raw !== "string") return;
+      let m: Up;
+      try { m = JSON.parse(raw) as Up; } catch { ws.close(4000, "not JSON"); return; }
+      const d = ws.data;
+      if (m.type === "hello") {
+        if (m.protocol !== SOCKET_PROTOCOL) { ws.close(CLOSE.badProtocol, `protocol ${SOCKET_PROTOCOL}`); return; }
+        if (typeof m.token !== "string" || !same(m.token, state.token)) { ws.close(CLOSE.unauthorized, "the page token is missing or wrong"); return; }
+        d.authed = true;
+        d.since = Math.max(0, Number(m.since) || 0);
+        d.interest = m.interest ?? { all: true };
+        sync(ws, true);
+        return;
+      }
+      if (!d.authed) { ws.close(CLOSE.unauthorized, "hello first"); return; }
+      if (m.type === "subscribe") {
+        const before = d.interest;
+        d.interest = m.interest ?? {};
+        d.want = resolveInterest(d.interest, d.cid, d.rid);
+        const more = added(before, d.interest);
+        if (more) grow(ws, more);
+        return;
+      }
+      if (m.type === "fire" || m.type === "read" || m.type === "raw") { await call(ws, m); return; }
+      if (m.type === "resync") { d.since = 0; sync(ws, false); return; }
+    },
+    close(ws) { leave(ws); },
+  };
+
+  function push(name: string, round: number, frame: Uint8Array): void {
+    for (const ws of peers.get(name) ?? []) {
+      const d = ws.data;
+      if (!d.authed) continue;
+      if (!d.ready) { d.buffer.push({ round, frame }); continue; }
+      if (ws.getBufferedAmount() > BEHIND) { ws.close(CLOSE.behind, "behind"); continue; }
+      give(ws, frame);
+    }
+  }
+
+  function generation(name: string, gen: number): void {
+    for (const ws of peers.get(name) ?? []) tell(ws, { type: "generation", gen });
+  }
+
+  const fetch = async (req: globalThis.Request, server: Server<Peer>): Promise<Response | undefined> => {
+    const host = req.headers.get("host") ?? "";
+    if (!localHost(host)) return text("host", 403);
+    const origin = req.headers.get("origin");
+    const upgrade = req.headers.get("upgrade")?.toLowerCase() === "websocket";
+    if ((req.method !== "GET" && req.method !== "HEAD" || upgrade) && origin && origin !== `http://${host}`) return text("origin", 403);
+
+    const url = new URL(req.url);
+    const parts = url.pathname.split("/").filter(Boolean);
+    if (parts.length === 0) return html(state.pages[""]!);
+
+    // /ws/NAME: a window's socket to the baba; the token comes in its hello.
+    if (parts[0] === "ws" && parts[1] && parts.length === 2) {
+      if (!names.has(parts[1])) return text("notfound", 404);
+      const data: Peer = { name: parts[1], authed: false, since: 0, ready: false, buffer: [], queue: Promise.resolve(), cid: new Map(), rid: new Map(), interest: { all: true }, want: resolveInterest({ all: true }, new Map(), new Map()) };
+      if (server.upgrade(req, { data })) return undefined;
+      return text("upgrade", 400);
+    }
+
+    if (parts[0] === "assets" && parts[1]) {
+      const a = state.assets[parts.slice(1).join("/")];
+      return a ? new Response(a.bytes, { headers: { "content-type": a.mime, "cache-control": "no-store" } }) : text("notfound", 404);
+    }
+
+    if (parts[0] === "api") {
+      const t = tokenOf(req);
+      if (!t || !same(t, state.token)) return json({ error: { code: "unauthorized", message: "the page token is missing or wrong" } }, 401);
+      if (parts[1] === "projects" && parts[2] === "refresh") {
+        if (req.method !== "POST") return json({ error: { code: "notfound", message: "no such route" } }, 404);
+        const a = await ask<"refresh">({ type: "refresh" });
+        return a.ok ? json(a.value) : failed(a);
+      }
+      // /api/projects/add: remember a directory's baba, or make one there first; the kernel re-reads the registry and the new one opens.
+      if (parts[1] === "projects" && parts[2] === "add") {
+        if (req.method !== "POST") return json({ error: { code: "notfound", message: "no such route" } }, 404);
+        let body: { dir?: unknown; init?: unknown; name?: unknown; title?: unknown } = {};
+        try { body = await req.json() as typeof body; } catch { return json({ error: { code: "args", message: "the body is not JSON" } }, 400); }
+        if (typeof body.dir !== "string" || !body.dir) return json({ error: { code: "args", message: "dir: the directory, absolute" } }, 400);
+        const a = await ask<"add">({ type: "add", dir: body.dir, init: body.init === true, ...(typeof body.name === "string" && body.name ? { name: body.name } : {}), ...(typeof body.title === "string" && body.title ? { title: body.title } : {}) });
+        return a.ok ? json(a.value) : failed(a);
+      }
+      if (parts[1] === "projects") return json({ projects: state.projects, voss: state.voss, home: state.home });
+      // /api/dirs?path=: the directories under one, for picking where a baba is or goes.
+      if (parts[1] === "dirs" && parts.length === 2) {
+        const a = await ask<"browse">({ type: "browse", path: url.searchParams.get("path") ?? "" });
+        return a.ok ? json(a.value) : failed(a);
+      }
+      // /api/voss: which voss runs and whether a newer one is installed; /api/voss/restart stops it to come back as that one.
+      if (parts[1] === "voss" && parts.length === 2) return json(state.voss);
+      if (parts[1] === "voss" && parts[2] === "restart" && parts.length === 3) {
+        if (req.method !== "POST") return json({ error: { code: "notfound", message: "no such route" } }, 404);
+        const a = await ask<"restart">({ type: "restart" });
+        return a.ok ? json(a.value) : failed(a);
+      }
+      const name = parts[2];
+      if (!name || !names.has(name)) return json({ error: { code: "nokey", message: `no project ${name ?? ""}` } }, 404);
+      if (parts[1] === "describe") {
+        const a = await ask<"describe">({ type: "describe", name, since: Number(url.searchParams.get("since")) || 0 });
+        return a.ok ? json(a.value satisfies Described) : failed(a);
+      }
+      if (req.method !== "POST") return json({ error: { code: "notfound", message: "no such route" } }, 404);
+      let body: unknown = {};
+      try { body = await req.json(); } catch { return json({ error: { code: "args", message: "the body is not JSON" } }, 400); }
+      let m: Unnumbered<Call> | null = null;
+      // ?coerce reads shell strings as the schema's numbers and booleans: the CLI's way in. ?key=K makes a retry answer the same.
+      const key = url.searchParams.get("key");
+      if ((parts[1] === "fire" || parts[1] === "read") && parts[3]) m = { type: "call", name, kind: parts[1], target: parts[3], args: body, ...(url.searchParams.has("coerce") ? { coerce: true } : {}), ...(key ? { key } : {}) };
+      else if (parts[1] === "state") m = { type: "call", name, kind: "state", since: Number((body as { since?: unknown }).since) || 0 };
+      else if (parts[1] === "raw" && parts[3] && RAW.has(parts[3])) m = { type: "call", name, kind: "raw", raw: { op: parts[3], ...(body as object) } as Raw };
+      if (!m) return json({ error: { code: "notfound", message: "no such route" } }, 404);
+      const a = await ask<"call">(m);
+      return a.ok ? json({ value: a.value }) : failed(a);
+    }
+
+    // /view/NAME/GEN/ is the view's index at a generation, /view/NAME/GEN/PATH one of its outputs.
+    // A generation's bundle never changes, so it may be cached for good; an older generation's URL gets the current one, uncached.
+    if (parts[0] === "view" && parts[1] && parts[2]) {
+      if (!names.has(parts[1])) return text("notfound", 404);
+      const path = parts.slice(3).join("/");
+      const a = await ask<"view">({ type: "view", name: parts[1], path: path || undefined });
+      if (!a.ok) return json({ error: { code: a.code, message: a.message } }, status(a.code) === 404 || a.code === "notfound" ? 404 : 500);
+      const cache = parts[2] === String(a.gen) ? "public, max-age=31536000, immutable" : "no-store";
+      if ("index" in a) return Response.json({ gen: a.gen, ...a.index }, { headers: { "cache-control": cache } });
+      return new Response(a.file.bytes as Uint8Array<ArrayBuffer>, { headers: { "content-type": a.file.type, "cache-control": cache } });
+    }
+
+    // /NAME/ is the baba's launcher, /NAME/APP/PATH one of its apps at a path; the one page serves them all, and the desktop reads the address.
+    if (names.has(parts[0]!)) {
+      if (parts.length === 1 && !url.pathname.endsWith("/")) return Response.redirect(`/${parts[0]}/${url.search}`, 302);
+      return html(state.pages[parts[0]!]!);
+    }
+    return text("notfound", 404);
+  };
+
+  return { fetch, websocket, push, generation };
+}

package/src/server/main.ts

@@ -0,0 +1,45 @@
+// The GUI server: a child of the kernel with nothing of its own. It
+// listens on loopback when the kernel says `serve`, answers from the
+// memory that message filled, forwards describe, view and call, and fans
+// each round's frame out to the windows on their sockets.
+import { ParentTransport } from "../transport/transport.ts";
+import type { FromServer, ToServer, Serve } from "./messages.ts";
+import { edge, type Ask, type Edge, type Peer } from "./edge.ts";
+
+const kernel = new ParentTransport<FromServer, ToServer>();
+const pending = new Map<number, (m: ToServer) => void>();
+let nextId = 1;
+let server: import("bun").Server<Peer> | null = null;
+let served: Serve | null = null;
+let live: Edge | null = null;
+
+const ask: Ask = (m) => new Promise((resolve) => {
+  const id = nextId++;
+  pending.set(id, resolve as (m: ToServer) => void);
+  kernel.send({ ...m, id } as unknown as FromServer);
+});
+
+kernel.onMessage((m) => {
+  if (m.type === "serve") {
+    if (server) return;
+    try {
+      // A describe long poll is silent for up to 25 s; Bun closes a silent connection after 10 s unless told otherwise.
+      served = m;
+      live = edge(m, ask);
+      server = Bun.serve<Peer>({ hostname: m.hostname, port: m.port, idleTimeout: 60, fetch: live.fetch, websocket: live.websocket });
+      kernel.send({ type: "listening", hostname: server.hostname ?? m.hostname, port: server.port ?? m.port });
+    } catch (err) {
+      kernel.send({ type: "failed", error: err instanceof Error ? err.message : String(err) });
+    }
+    return;
+  }
+  // The edge reads the projects and pages from the served state on every request.
+  if (m.type === "projects") { if (served) { served.projects = m.projects; served.pages = m.pages; } return; }
+  if (m.type === "voss") { if (served) served.voss = m.voss; return; }
+  if (m.type === "round") { live?.push(m.name, m.round, m.frame); return; }
+  if (m.type === "generation") { live?.generation(m.name, m.gen); return; }
+  const resolve = pending.get(m.id);
+  pending.delete(m.id);
+  resolve?.(m);
+});
+kernel.send({ type: "ready" });

package/src/server/messages.ts

@@ -0,0 +1,97 @@
+// What crosses between the kernel and the GUI server. The server has no
+// files and no projects of its own: the kernel fills its memory with
+// `serve`, then answers every request it forwards, matched by id.
+import type { Described } from "../baba/node.ts";
+import type { Raw } from "../ecs/runtime.ts";
+import type { Interest } from "./protocol.ts";
+
+// ---- kernel → server ---------------------------------------------------
+
+/** Which voss runs, and whether a newer one is installed: then this one is stale, serving what it has until the restart. */
+export interface Voss {
+  version: string; sha: string; at: string; dev: boolean; pid: number;
+  /** Under the service: a clean exit is a restart. Otherwise the restart re-runs the same command. */
+  kept: boolean;
+  stale: boolean;
+  installed: { version: string; sha: string; at: string } | null;
+}
+
+/** Everything the server holds, sent once: it listens when this arrives. */
+export interface Serve {
+  type: "serve";
+  hostname: string;
+  port: number;
+  token: string;
+  voss: Voss;
+  projects: ProjectEntry[];
+  /** The user's home directory: the picker writes paths under it as ~/… and starts browsing there. */
+  home: string;
+  /** The page per scope: "" is the picker's, a project's name its own. The token meta is already in. */
+  pages: Record<string, string>;
+  /** The GUI's build, by path under /assets/. */
+  assets: Record<string, Asset>;
+}
+
+/** A registered project; `parent` is the nearest registered project whose directory holds it, for nesting. */
+export interface ProjectEntry { name: string; title: string; dir: string; parent: string | null }
+export interface Asset { mime: string; bytes: Uint8Array<ArrayBuffer> }
+
+export type { Described };
+
+/** A failed request: `code` is the node's (noaction, noquery, args, noview, bundle, down, …). */
+export interface Failure { ok: false; code: string; message: string }
+
+export type DescribeAnswer = { type: "describe-answer"; id: number } & ({ ok: true; value: Described } | Failure);
+/** What the view's build produced, by path under /view/NAME/GEN/: the entry to import, the stylesheets to attach. */
+export interface ViewIndex { entry: string; css: string[]; paths: string[] }
+export type ViewAnswer = { type: "view-answer"; id: number } & ({ ok: true; gen: number; index: ViewIndex } | { ok: true; gen: number; file: { type: string; bytes: Uint8Array } } | Failure);
+export type CallAnswer = { type: "call-answer"; id: number } & ({ ok: true; value: unknown; /** The round a fire or a raw write ran in. */ round?: number } | Failure);
+
+/** The registry changed: the projects and their pages, replacing what `serve` sent. */
+export interface Projects { type: "projects"; projects: ProjectEntry[]; pages: Record<string, string> }
+/** What a refresh did: the projects now open, and the directories that did not load, with why. */
+export interface Refreshed { projects: ProjectEntry[]; errors: { dir: string; error: string }[] }
+export type RefreshAnswer = { type: "refresh-answer"; id: number } & ({ ok: true; value: Refreshed } | Failure);
+
+/** A round of a project's live generation, as the frame every window of it gets. */
+export interface RoundPush { type: "round"; name: string; round: number; frame: Uint8Array }
+/** A project's generation advanced: its windows re-read the contract and resync. */
+export interface Generation { type: "generation"; name: string; gen: number }
+
+/** Voss's own standing changed: a newer one is installed. */
+export interface VossPush { type: "voss"; voss: Voss }
+export type RestartAnswer = { type: "restart-answer"; id: number } & ({ ok: true; value: { restarting: true; kept: boolean } } | Failure);
+/** A directory and what is under it: each child, whether it holds a baba, and whether it is already remembered. */
+export interface Browsed { path: string; home: string; parent: string | null; baba: boolean; known: boolean; dirs: { name: string; path: string; baba: boolean; known: boolean }[] }
+export type BrowseAnswer = { type: "browse-answer"; id: number } & ({ ok: true; value: Browsed } | Failure);
+/** What an add did: the project made or remembered, and the registry re-read. */
+export type AddAnswer = { type: "add-answer"; id: number } & ({ ok: true; value: Refreshed & { name: string; dir: string } } | Failure);
+
+export type ToServer = Serve | Projects | VossPush | DescribeAnswer | ViewAnswer | CallAnswer | RefreshAnswer | RestartAnswer | BrowseAnswer | AddAnswer | RoundPush | Generation;
+
+// ---- server → kernel ---------------------------------------------------
+
+export interface Ready { type: "ready" }
+export interface Listening { type: "listening"; hostname: string; port: number }
+export interface Failed { type: "failed"; error: string }
+
+/** `since` > 0 asks the kernel to wait until the project passes that generation, or a timeout. */
+export interface Describe { type: "describe"; id: number; name: string; since: number }
+/** The view's index when `path` is absent, else that output of its current bundle. */
+export interface View { type: "view"; id: number; name: string; path?: string }
+/** The baba's contract and state: fire an action, read a query, the state past a round, a raw write. */
+export type Call =
+  | { type: "call"; id: number; name: string; kind: "fire" | "read"; target: string; args: unknown; coerce?: boolean; key?: string }
+  | { type: "call"; id: number; name: string; kind: "state"; since: number; frame?: true; wait?: boolean; parts?: Interest }
+  | { type: "call"; id: number; name: string; kind: "raw"; raw: Raw };
+
+/** Re-read the registry: open the projects it gained, retire the ones it lost. */
+export interface Refresh { type: "refresh"; id: number }
+/** Stop and start again, as the newer installed voss. */
+export interface Restart { type: "restart"; id: number }
+/** The directories under `path`, the user's home when empty: for picking where a baba is, or goes. */
+export interface Browse { type: "browse"; id: number; path: string }
+/** Remember a project at `dir`; with `init`, make its .baba first, named and titled as given or after the directory. */
+export interface Add { type: "add"; id: number; dir: string; init: boolean; name?: string; title?: string }
+
+export type FromServer = Ready | Listening | Failed | Describe | View | Call | Refresh | Restart | Browse | Add;

package/src/server/protocol.ts

@@ -0,0 +1,37 @@
+// The socket between a window and the GUI server: what each side says.
+// Browser-safe; both ends import it, so the two vocabularies are one.
+
+/**
+ * What a window asks to follow, by name: everything; the presence of some
+ * components (which entities have them, for lists); the values of some
+ * (for predicates, orders and whole columns); the values of some parts, an
+ * entity's component (for rows); some resources. The edge cuts every frame
+ * to it. Empty means nothing.
+ */
+export interface Interest { all?: boolean; presence?: string[]; values?: string[]; parts?: Record<string, number[]>; resources?: string[] }
+
+/** A component or resource as the frame lays it out: its name and its schema's JSON. */
+export interface Declared { name: string; json: { [k: string]: unknown } }
+
+export const SOCKET_PROTOCOL = 1;
+
+/** What a window sends: its hello, what it follows, its calls, a resync. */
+export type Up =
+  | { type: "hello"; protocol: number; token: string | null; since: number; interest: Interest }
+  | { type: "subscribe"; interest: Interest }
+  | { type: "fire"; id: number; name: string; args: unknown; key?: string }
+  | { type: "read"; id: number; name: string; args: unknown }
+  | { type: "raw"; id: number; op: string; [k: string]: unknown }
+  | { type: "resync" };
+
+/** What the server sends as text; frames come as bytes. */
+export type Down =
+  | { type: "welcome"; protocol: number; gen: number; components: Declared[]; resources: Declared[] }
+  | { type: "result"; id: number; ok: true; value: unknown; round?: number }
+  | { type: "result"; id: number; ok: false; code: string; message: string }
+  | { type: "generation"; gen: number };
+
+export type Welcome = Extract<Down, { type: "welcome" }>;
+
+/** The close codes the server uses; a window stops trying on the first three. */
+export const CLOSE = { badProtocol: 4002, unauthorized: 4001, unknown: 4004, down: 4005, behind: 4008 } as const;

package/src/services/args.ts

@@ -0,0 +1,45 @@
+// Checks at the kernel's edge: a runtime sends whatever it likes, so every
+// argument is a shape to verify before a service acts on it.
+import { ServiceError, type Who } from "../kernel/context.ts";
+
+export function string(v: unknown, what: string): string {
+  if (typeof v !== "string") throw new ServiceError("args", `${what}: expected a string`);
+  return v;
+}
+
+export function optional<T>(v: unknown, what: string, check: (v: unknown, what: string) => T): T | undefined {
+  return v === undefined || v === null ? undefined : check(v, what);
+}
+
+export function bytes(v: unknown, what: string): string | Uint8Array {
+  if (typeof v === "string" || v instanceof Uint8Array) return v;
+  throw new ServiceError("args", `${what}: expected a string or bytes`);
+}
+
+export function strings(v: unknown, what: string): string[] {
+  if (!Array.isArray(v)) throw new ServiceError("args", `${what}: expected an array of strings`);
+  return v.map((s, i) => string(s, `${what}[${i}]`));
+}
+
+export function object(v: unknown, what: string): Record<string, unknown> {
+  if (typeof v !== "object" || v === null || Array.isArray(v)) throw new ServiceError("args", `${what}: expected an object`);
+  return v as Record<string, unknown>;
+}
+
+export function record(v: unknown, what: string): Record<string, string> {
+  const o = object(v, what);
+  for (const [k, x] of Object.entries(o)) string(x, `${what}.${k}`);
+  return o as Record<string, string>;
+}
+
+export function params(v: unknown, what: string): (string | number | bigint | boolean | null | Uint8Array)[] {
+  if (!Array.isArray(v)) throw new ServiceError("args", `${what}: expected an array`);
+  return v.map((p, i) => {
+    if (p === null || p === undefined) return null;
+    if (typeof p === "string" || typeof p === "number" || typeof p === "bigint" || typeof p === "boolean" || p instanceof Uint8Array) return p;
+    throw new ServiceError("args", `${what}[${i}]: expected a string, number, boolean, bytes or null`);
+  });
+}
+
+/** What a service module exports: one handler per operation of its interface, over unchecked arguments. */
+export type Ops<S> = { [K in keyof S]: (who: Who, args: unknown[], signal: AbortSignal) => Promise<unknown> | AsyncIterable<unknown> };

package/src/services/exec.ts

@@ -0,0 +1,69 @@
+// Programs on the machine, resolved on PATH and run by
+// the kernel in the project, with a small environment and an owned lifetime.
+import { stat } from "node:fs/promises";
+import { ServiceError, type Exec, type Who } from "../kernel/context.ts";
+import { string, optional, strings, object, record, type Ops } from "./args.ts";
+import { inside } from "./fs.ts";
+import { ExecutionHost } from "../exec/host.ts";
+import type { Command } from "../exec/wire.ts";
+
+export const Cap = 10 * 60_000;
+
+/** What a program inherits from the kernel: enough to find things and write temp files, nothing of ours. */
+const Inherited = ["PATH", "HOME", "LANG", "TMPDIR"];
+
+/** The kernel's PATH, then where a person's tools usually are, voss's own bin first: a daemon under launchd has the system's PATH only. */
+function lookupPath(): string {
+  const home = process.env.HOME ?? "";
+  const extra = [home && `${home}/.voss/bin`, home && `${home}/.bun/bin`, home && `${home}/.local/bin`, "/opt/homebrew/bin", "/usr/local/bin"].filter(Boolean) as string[];
+  const have = (process.env.PATH ?? "").split(":").filter(Boolean);
+  return [...have, ...extra.filter((d) => !have.includes(d))].join(":");
+}
+
+/** One host per kernel services instance, never a global process registry. */
+export function execution(): Ops<Exec> {
+  const host = new ExecutionHost();
+  const command = async (who: Who, [p, a, o]: unknown[]): Promise<Command> => {
+    const program = string(p, "program");
+    const args = optional(a, "args", strings) ?? [];
+    const options = optional(o, "options", object) ?? {};
+    const cwd = optional(options.cwd, "options.cwd", string);
+    const input = optional(options.input, "options.input", string);
+    const env = optional(options.env, "options.env", record) ?? {};
+    const timeout = options.timeout === undefined ? Cap : options.timeout;
+    if (timeout !== null && (typeof timeout !== "number" || !Number.isSafeInteger(timeout) || timeout <= 0)) throw new ServiceError("args", "timeout must be positive whole milliseconds or null");
+    if (options.interactive !== undefined && typeof options.interactive !== "boolean") throw new ServiceError("args", "interactive must be boolean");
+    const PATH = lookupPath();
+    const path = Bun.which(program, { PATH });
+    if (!path) throw new ServiceError("notfound", `${program} is not on PATH of this machine`);
+    const dir = cwd === undefined ? who.project : await inside(who, cwd);
+    if (!(await stat(dir).catch(() => null))?.isDirectory()) throw new ServiceError("notfound", `options.cwd: ${cwd} is not a directory`);
+    const base = { ...Object.fromEntries(Inherited.filter((k) => process.env[k] !== undefined).map((k) => [k, process.env[k]!])), PATH };
+    return { program: path, args, cwd: dir, env: { ...base, ...env }, input, timeout, interactive: options.interactive === true };
+  };
+  return {
+    async run(who, args, signal) {
+      if (signal.aborted) throw new ServiceError("failed", "execution cancelled");
+      const c = await command(who, args);
+      if (c.interactive) throw new ServiceError("args", "interactive stdin requires exec.stream");
+      let stdout = "", stderr = "", code = 0, size = 0;
+      const out = new TextDecoder(), err = new TextDecoder();
+      for await (const e of host.stream(who, c, signal)) {
+        if (e.type === "exit") code = e.code;
+        else if (e.type === "stdout" || e.type === "stderr") {
+          size += e.data.byteLength;
+          if (size > 8 * 1024 * 1024) throw new ServiceError("failed", "execution output exceeds 8 MiB; use exec.stream");
+          if (e.type === "stdout") stdout += out.decode(e.data, { stream: true }); else stderr += err.decode(e.data, { stream: true });
+        }
+      }
+      return { code, stdout: stdout + out.decode(), stderr: stderr + err.decode() };
+    },
+    async *stream(who, args, signal) {
+      if (signal.aborted) throw new ServiceError("failed", "execution cancelled");
+      yield* host.stream(who, await command(who, args), signal);
+    },
+    async write(who, [ref, input], signal) {
+      await host.write(who, string(ref, "process"), input === null ? null : string(input, "input"), signal);
+    },
+  };
+}